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Preface 



This manual describes the macro instructions ptovided by 
the IBIVi System/a iVlodel 15. The publication ;<; ^.tended 
for persons who are programming in the Basic Assembler 
Language or its equivalent and who are taniiliai -witt. tiie 
concept of macro instructions and syslem progranirriing 
for the IBM System/3 Model 15. 
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• Error conditions detected by the macro ;)rocessor. 
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Chapter 1: Introduction 



A macro instruction is a source statement that causes 
generation of a predetermined set of assembler statements 
each time the macro instruction is used. The Model 15 System 
Control Program provides macro instructions which per- 
form both system services and input/output device support. 
By using these macro instructions, you can perform both 
system and input/output operations with less coding. 

Figure 1 is an overview of the operation of the macro 
processor. The OCL statements used to call the macro 
processor are explained in Chapter 3: OCL and Sample 
Program. 



WRITING MACRO INSTRUCTIONS 

You code macro instructions as follows: 



Operands specify the available services and options. The 
operands must start in column 14, and are written as 
follows: 

• Each operand consists of a keyword followed by a dash 
and a parameter. 

• Commas separate the operands; no blanks should be 
left between operands. 

• Keywords - those shown in capital letters - are coded 
exactly as shown. The keyword part of each operand 
must correspond to one of the keywords in the macro 
instruction description. 

• The parameter part of the operand must immediately 
follow the dash. 



Starting 
Column 1 



14 



72 



Name 


Operation 


Operands 


Continuation 


Symbol 
or blank 


Macro 
name 


No operands 
or one or more 
separated by 
conn mas 


Any nonblank 
character if 
continuation is 
being used 



Parameters — those shown in lowercase letters — indicate 
information you must supply. Some operands are not 
required. These optional operands are indicated by 
enclosing the operand within brackets [KEYWORD- 
parameter] . 

An option list for a keyword parameter is specified as 
follows: 



The name field can contain any valid assembler language 
symbolic name beginning in column 1. The name is 
assigned to the first byte of generated code. Since the name 
is optional, it is shown enclosed in brackets. 

The desired mnemonic operation code (macro instruction 
name) must appear as specified in the macro instruction 
description. The operation code must start in column 8. 

Keyword 
Dasli 
Parameter 




Operand Optional Default Option 
Operand Value List 



KEYWORD-A/B/C 

This list indicates that the keyword has the options 
A, B, or C. These are the only valid options for the 
keyword parameter. 

When the options Y/N are given in a macro instruction, 
Y indicates a yes response, N indicates a no response. 

The operands may be written in any order. If a key 
word is not specified, the default value is used. A 
default value is selected for optional keywords that are 
omitted. The default value is indicated in the macro 
instruction description by a line under the default option. 
For example, [KEY-A/B/C] indicates the option A is 
the default value. 
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This is your program 
It includes macro 
statements 




Load the macro processor ($MPXDV) 
OCL can be entered through the 
system input device or called from 
the procedure library. 



This indicates the beginning 
of the next job. 



This indicates the end of your job. 



IBM System/3 Model 15 
Macro Processor (SMPXDV) 



The macro processor reads source state- 
ments from either the system input de- 
vice or a source library. 

• All valid assembler statements and 
comments are placed in $SOURCE. 

• Macro statements are listed in 
SSOURCE, preceded by an 
asterisk and followed by the 
macro expansion. 

• Macro expansion statements are 
marked (by the macro processor) in 
position 96 in $SOURCE and indi- 
cated on the assembly listing by a 
plus sign (-I-) preceding the expan- 
sion statement. 

• Invalid statements are flagged and 
placed in $SOURCE. 



Statements placed in 
SSOURCE are used as 
source input to an 
assembler. 



Figure 1. Macro Processor Overview 
2 
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SYSTEM CONFIGURATION 

The minimum system configuration for using the Model 15 
macros is: 

• 5415 Processing Unit with at least 48K bytes of main 
storage. 

• 3277 Display Station Model 1 with Feature 4632. 
This comprises the IBM System/3 Model 15 CRT/Key- 
board, usually referred to in this manual as the CRT/ 
Keyboard. 

• Disk Storage Device. 

• A system input device. 

• 1403Printer Model 2,5, or Nl. 

The following input and output devices are supported: 

• 5424 Multi-Function Card Unit (MFCU) Model A1 or 
A2, 1442 Card Read Punch Model 6 or Model 7, or 
2560 Multi-Function Card Machine (MFCM) Model A1 
or A2. 

• 1403 Printer Model 2, 5, or Nl. 

• 3277 Display Station Model 1 with Feature Number 
4632 (CRT/Keyboard). This device can be used both 
as the system input device and the system log device. 

• 3410/3411 Magnetic Tape Subsystem Model 1,2, or 3. 

• 2501 Card Reader Model A1 or Model A2. 

• 3284 Printer 

• 3741 Data Station Model 1 or 2 or Programmable Work 
Station Model 3 or 4. 

• Disk Storage Requirements. 



Minimum 

5444 Disk Storage Drive, 


5704 


SCI 


SC2 


15A 


15B 


15C 


15D 


X 








Model A2 










3340 Direct Access Storags 




X 


X 


X 


Facility, Model A2 










Optional 










5444 Disk Storage Drive, 


X 








Model A3 










5445 Disk Storage, Models 1 , 


X 








2, and 3 










3340 Direct Access Storage 




X 


X 


X' 


Facility, Models 81 and B2 










3344 Direct Access Storage, 








X' 


Model A2 











' Mutually exclusive 

The macro processor operates under control of the IBM 
System/3 Model 15 System Control Program. 



MACRO INSTRUCTIONS PROVIDED 

The macro instructions provided by the Model 15 System 
Control Program (SCP) and the functions they perform are 
shown in Figure 4. 

.All macros you want to use must be in the source library on 
the program pack or the system pack. The program pack is 
the disk pack from which the macro processor is loaded. 
The system pack is the disk pack from which initial program 
load (IPL) is performed. Note that the macro processor and 
IPL code may be on the same pack. 

You may want to delete some macro instructions iiom 
your library to reduce tln; amount of disk space required 
for the macro instructions. For instance, if your system 
does not include the 3410/3411 Magnetic Tape Subsystem, 
the tape macro instructions would be of no use to you. 
You can delete macro instructions from your !ib;ary by 
using the library maintenance irtiliry program, SMAiNT. 



Device Type Supported 



System Reader- 



System Log 



General SCP 



Gerneral I/O 



Card 



Macro 

Instruction 

Name 



SRLST 
SRLSD 
$READ 



$LWTO 
SLMSG 
$LOG 
$LOGD 



SROLL 

$FIND 

$LOAD 

SFTCH 

$XCTL 

$TRL 

STRTB 

$TRAN 

$SNAP 

SDATE 

STIOB 

$SIT 

STOD 

$RIT 

$EOJ 



$ALOC 

SOPEN 

$CI<L 

$CHK 

$CLOS 

SDTFO 

SCOMN 



$DTFC 
$GETC 
$PUTC 
$GPC 



Function 



Generate reader parameter list 
Offsets in reader parameter list 
Linkage to system reader 



Generate parameter list for WTO or WTOR 
Generate parameter list for halt message on system log 
Linkage to system log 
Offsets in log parameter list 



Rollout/rollin linkage (5704-SC1 Only) 

Find a directory entry 

Load a module 

Load a module and pass control 

Load a module and exchange control 

Generate a translate parameter list 

Generate a translate table 

Generate an interface to the translate routine 

Snap dump main storage 

Retrieve system date 

Generate timer lOB 

Set interval timer 

Return time of day and system date 

Return amount of time left in timer interval 

End of job 



Allocate disk space or device 

Prepare an I/O device 

Generate a checklist 

Check for I/O completion for BSCA operations 

Prepare a device for termination 

DTF offsets for all devices 

Generate equates 



Define the file for a card device 
Construct a card GET interface 
Construct a card PUT interface 
Construct a GET or a PUT interface to a card file 



Figure 4 (Part 1 of 21. Macro Instructions 
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Macro 




instsuction 


Device Type Supported 


Matne 


Printer 


.$DTFP 




SPUTP 


Disk 


SDTFD 




$GETD 




SPUTD 




$i(3BD 




$IOED 




$RDD 




SWRTD 




$WAIT 


Tape 


SDTFT 




SGETT 




SPIJTT 




$RDT 




$V\/RTT 




SCILT 




SWTT 


Device Independent 


SDTFI 




$GETI 




SPUTI 


CRT/Keyboard 


$D IFS 




SGETS 




$PUTS 




$PGS 




SCQEP 




$PF|<Y 




SPFKT 


3741 


SiL.vfFK 




$GETK 




$PUTK 



1- UIl'-Tif'i. 

f,)»fiii.' ;li.. fii(: r,> : ..,,:,,. 
ConsUnci a iJii'it;'; P^i i inteifaor 

nefine the iHe for disk 
ConsiiMct a disk GFT intoifar-p 

Cr)n'?!MiCt j (jisk PU': in!P.i--!ria 

(iicnei hU' a di-^k ' ' ; r.joiiK 

' "-'"ifvi ■: '■ ■• 'set' '.<; .i:, i , ( j h^,-cK f-'i ciisk 

rierli! fiOi;l '!'<■!- 

Wyit l;^i disi^" i/() cnmpiei i^Mi 

Define !i \i'. i ..'■' !oi !-i;]e 

Cfuistiuci H taiie (tF i ■rireriace 

i:onsTrL:.'t a tape PL' ! iiiie? ■.•v: 

Re.ad troiri f.ipe 

Write to tape 
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Chapter 2. Macro Instruction Statements 



You code macro instructions to generate a blocl< of 
assembler statements that perform a certain function. Some 
functions may be the same each time they are used, others 
may be modified by specifying different operands. This 
chapter explains the System/3 Model 15 macro instructions 
in detail. 

The macro instructions are grouped in this chapter accord- 
ing to the functions they perform: 

• System services 

• Input/output support 

Input/output support macro instructions are further 
divided according to the device supported. 

PROGRAMMING CONSIDERATIONS 

When you use the macro processor you should remember 
the following restrictions: 

1. The generated code for some macro instructions uses 
register 1; the generated code for other macro instruc- 
tions uses register 2. You should save the contents of 
the register used by the generated code before issuing 
the macro instruction; otherwise, the contents are 
destroyed. These macro instructions use register 1 : 

$PFKY 

SPFKT 

$RDD 

$TRAN 

SWA IT 

$WRTD 

These macro instructions use register 2: 



$ALOC 


$GETT 


SPUTS 


$CHK 


$GPC 


SPUTT 


SCLOS 


$LOAD 


SRDT 


SCTLT 


SLOG 


SREAD 


$DATE 


SOPEN 


SRIT 


$FIND 


SPGS 


SSIT 


$FTCH 


SPUTC 


STOD 


$GETC 


SPUTD 


SWRTT 


$GETD 


SPUTI 


SWTT 


$GETI 


SPUTK 


SXCTL 


$GETK 


SPUTP 




$GETS 







The code generated by the macros is assigned labels, 
which begin with the dollar sign (S). To avoid dupli- 
cate label errors, you should not use the dollar sign 
as the first character of a label. 



SYSTEM SERVICES MACROS 

By using system services macro instructions, you can com- 
municate with the Model 15 system control program. 

These macro instructions can do the following: 

• Read records from the system input device. 

• Log and write error messages. 

• Determine the location of an object module on disk. 

• Obtain object modules from disk and load them into 
main storage. 

• Pass control to modules in main storage. 

• Terminate the current job. 

The system services macro instructions are divided into 
three groups: 

1. System reader macro instructions, which provide 
support and linkage to the system reader function. 

SREAD 
SRLSD 
SRLST 

2. System log macro instructions, which provide support 
and linkage to system log functions. 

SLMSG 
SLOG 
SLOGD 
SLWTO 
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3. General SCP macro instructions, which provide 
linkage to system functions. 

SDATE 

$EOJ 

SFIND 

SFTCH 

$LOAD 

$ROLL (5704-SCl only) 

SRIT 

$SIT 

SSNAP 

STIOB 

$TRAN 

$TRL 

$TRTB 

$TOD 

$XCTL 



To call the system reader, you must do the following; 

1 . Use the SRLST macro to construct a parameter list as 
input to the system reader routine. 

2. Use the $RLSD macro instruction to establish equates 
for the system reader parameter list. 

3. Issue the SREAD macro instruction. 

The $READ macro generates the code to load the parameter 
list address Into register 2, set the operation code, call the 
system reader routine, and check the return codes. Because 
the return code is in the same byte as the operation code, 
the operation code must be reset before each call. The 
$RLSD macro is provided to generate the offsets into the 
parameter list, the values for the operation codes, and the 
values for the return codes. 



System Reader Support 

You read a record from the system reader by calling the 
system reader routine through the $READ macro instruc- 
tion. The system reader may be one of the following: 

• CRT/Keyboard. Only 96-byte, single-buffered input is 
allowed for this device. Double buffering is ignored. 

• 2501 Card Reader. Single and double buffering are 
supported. Only 80 bytes of the 96-byte buffer are 
used as input; the remaining 16 bytes are cleared to 
blanks. 



Generate a System Reader Parameter List ($RLST) 
This macro instruction generates a reader parameter list. 
The format of the SRLST macro instruction is: 



Namel SRLST BUF 1 -addi ess.WORK-addiess |,BUF2-address] 



BUFl address specifies the address of the leftmost byte of 
a 96-byte buffer that is aligned on a 128-byte boundary. 
This operand is required. 



• 2560 Multi-Function Card Machine (MFCM). Single and 
double buffering are supported. Only 80 bytes of the 
96-byte buffer are used as input; the remaining 16 bytes 
are cleared to blanks. Support for both the primary 
(MFCM) and secondary (MFCM2) hoppers is provided. 

• 1442 Card Read Punch. Single and double buffering are 
supported. Only 80 bytes of the 96-byte buffer are used 
as input; the remaining 16 bytes are cleared to blanks. 

• 5424 Multi-Function Card Unit (MFCU). Both single and 
double buffering are supported. Support for both the 
primary (MFCU1) and secondary (MFCU2) hoppers 

is provided. All 96 bytes are used as input. 

• Directly attached 3741 Data Station Model 1 or 2 or 
Programmable Work Station Model 3 or 4. Single and 
double buffering are supported. Only 96-byte records 
may be read. 



WORK address specifies the address of the leftmost byte of 
a 47-byte work area; this operand is required. 



BUF2-address specifies the address of the leftmost byte of 
a 96-byte buffer that is aligned on a 128-byte boundary. 
This is the second buffer if double buffering is used; if this 
operand is not specified, single buffering is assumed. 

System Reader Parameter List Offsets ($RLSDj 

This macro instruction generates a list of equates used to 
label the fields in the system reader parameter list. $RLSD 
also generates the operation codes and return codes used 
by SREAD. To avoid duplicate labels, you should use this 
macro instruction only once in a program. 

The format of the $RLSD macro instruction is: 





SRLSD 





Linkage to System Reader Function ($READ) 

This macro instruction generates the linkage to call the 
systenn reader function and check for return codes. 

The format of the $READ macro instruction is: 



[Name] 


$READ 


[LIST-addressl [,OPC-code) [,EOF-address] 
[,EOJ-address] [,ERR-address] 



LIST-address specifies the address of the leftmost byte of 
the system reader parameter list. If this operand is not 
specified, the address of the parameter list is assumed to be 
in register 2. 



OPC-code specifies the operation code for this read request. 
The allowable codes and their meanings are: 

Code Meaning 

RD Set the operation code to read one record 

from the system reader single buffer. 
RDF Set the operation code to read one record 

from the system reader into buffer 1 and 

start -a read on buffer 2. 
RDD Set the operation code to wait on buffer 2, 

switch the buffers, and start the other 

buffer. 
RDL Set the operai.o,. ..ode to wait on buffer 2, 

and switch the buffers; do not start the 

other buffer. 
N Do not set any operation code. If this value 

is specified, it is your responsibility to set the 

operation code before issuing this macro. 

The default value for this operand is RD. 

EOF-address specifies the address in your program that re- 
ceives control when an end-of-file statement (/*, /&, or /.) 
is detected. If this operand is not supplied, no code is gen- 
erated to check for the end-of-file condition. 



EOJ-address specifies the address of the routine that should 
get control if an end -of -job or end-of-step statement {/& or 
/.) was detected on the previous read. If this operand is not 
specified, the test for the return code is not generated. 
Once a /& statement is read from the system reader, nothing 
can be read from the system reader until the end of step. 
Once a / . statement is read from the system reader, nothing 
can be read from the system reader until the end of job. 



ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code. 

Notes: 

1. If ERR or EOF addresses are not specified, you should 
check the return code in your program to determine the 
outcome of the operation. 

2. When double buffering is used, return code should be 
provided to return to the read macro instruction until 
end-of-file (EOF) is received. When the program's EOF 
is dependent upon a user-defined EOF statement, the 
last request to the read macro should be a wait only call; 
this will allow all outstanding read requests to be cleared 
from the device queues. The last wait request is necessary 
to prevent overlaying the system input work area before 
the program reaches end of job. 

System Log Support 

Specifying a $LOG macro instruction in your program gen- 
erates a call to system log (system log is a group of system 
output routines which provide communication with the 
operator). You may want to use system log to notify the 
operator of error conditions, error recovery procedures, and 
the validity of previous operator responses to messages. 
If the operator selects an invalid option in response to a 
message, the response is not accepted by system log. 
Instead, another message is issued to the operator until a 
correct option is taken. 

Note: When an immediate cancel (option 3) is selected, 
control is passed directly to the end-of-job (EOJ) routine 
by system log. 

Two types of printed output are available through system 
log — logs and messages. Both are printed on the system 
log device. 

• A log is a four- or six-character statement that identifies 
the type and source of an error. 

• A message is a printed statement which can be used to 
indicate errors that have occurred or to issue instructions 
to the operator, such as requesting that a disk file be 
placed on a certain drive. 

Logs and messages can be issued with or without being 
displayed on the 3277. 

Three devices can be used as the system log device: the 
1403 printer, the 3284 printer, or the CRT/Keyboard. 
You can change devices by entering a LOG statement in 
your job stream. 
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To use system log, you must do the following: 

1 . Build the log parameter list using the $LWTO or 
$LMSG macro. 

2. Use the $LOGD macro instruction to establish equates 
for the log parameter list. 

3. Issue the macro instruction: 



^Name] 



SLOG 



[LIST-address) [,OPIM0-address] 
[,OPN1 -address] [,0PN2-addressl 



4. Process the operator's reply in your program. 

Two types of messages can be displayed on the log: the 
system message and the message to the operator. 

The SLMSG macro instruction generates a parameter list to 
display the standard system message. You can also include 
from 1 to 107 characters of text with this message. The 
operator can respond to this message by pressing the PF12 
key, taking one of the four allowable options, then pressing 
ENTER. Option 0, 1, or 2 is returned to you for checking; 
option 3 means end-of-job. If the operator takes option 3, 
the system log routine goes directly to the end-of-job. 

The $LWTO macro instruction generates a parameter list to 
display a message to the operator. This message is from 1 
to 107 characters long and is prefixed with six characters 
which you specify using the $LWTO macro. You can re- 
quest a reply (1 to 72 characters) from the operator, but if 
no reply is requested, the operator responds to the message 
by pressing PF12, then ENTER. 



Reply Length Considerations Three, 36-character lines (107 
characters plus the CRT control character) are available for 
the message and reply. The number of characters allowed 
for the reply depends on the number of lines that contain 
test characters. Once a test character has been entered on 
a line, any non-text positions of that line cannot be used 
for a reply. Instead, the reply must begin on the next line. 
If the third line contains a text character, no reply can be 
made. For example: 



If the text length is: 

more than 1 character 

but less than 36 
more than 36 characters 

but less than 72 
more than 72 characters 

but less than 108 



The reply length can be: 

from 1 to 72 characters 
from 1 to 36 characters 
no reply can be made 



Generate a Parameter List for WTO or WTOR ($L WTO) 

This macro instruction generates a system log parameter list 
for the write-to-operator or write-to-operator-with-reply 
function. 

The format of the $LWTO macro instruction is: 




TLEN-number, TADR-address [.COMP-code] 
,HALT-code] [,SUBH-code] [,REPLY-Y/N] 
RLEN-number] [.RADR-address] 



TLEN-number specifies the text message length (an un- 
signed, non-zero, decimal value). This operand is required 
and can be from 1 to 107 characters long. 



For either of the message types, the $LOGD macro instruc- 
tion is specified to generate offsets into the parameter list 
and to define the meaning of the fields within the parameter 
list. 



TADR-address specifies the address of the leftmost byte of 
the text message; this operand is required. 



Text Lengtti Considerations: Message text is displayed on 
the CRT in one, two, or three 36-character lines, depend- 
ing on the text length. For example, if the text length is 
60 characters, it takes one line of 36 characters and 24 char- 
acters from the second line to display the message. 



COMP-code specifies the first two characters of the halt 
message. These characters are the component identification. 
If this operand is not specified, the default value is two 
blanks. 



HALT-code specifies the second two characters of the halt 
message - the halt identification. If this operand is not 
specified, the default value is two blanks. 



SUBH-code specifies the last two characters of the halt 
message - the subhalt identification. If this operand is not 
specified, the default value is two blanks. 
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REPL Y-Y or N specifies whether or not a reply is requested. 
If Y (yes) is specified, system log waits for the operator to 
reply. If N (no) is specified ot if this operand is omitted, no 
reply is allowed. 



COMP-code specifies the first two i:liaia(;ters of llie rnessiiqe 

tlie component description (CO. If thi'-, ojierand is nc^i 
specitifHi, two blanks are assismed. 



RLEN-number is ttie length of the reply (an unsigned, non- 
zero, decimal value, from 1 to 72). If REPLY-Y is specified, 
this operand is required. 



HAL T code specifies the second two characters of Uie 
message ■ the message identification (HH). If tliis opeiand 
is not specified, two blanks are assumed. 



RADR-address specifies the address of the leftmost byte of 
the reply area. If REPLY-Y is specified, this operand is 
required. 



SUBH code specifies the last two ciiaracters ui tfie message 

fhe subhalt identification (II). !f FOI^MAT B mi 
was specified and tliis operand is omitted, two blanks are 
assumed. 



I Generate a Parameter List for Message on System Log 
($LMSG) 

This macro instruction generates a system log parameter 
list for a log and/or message to the operator. 

The format of the $LMSG macro instruction is: 



[Name] 


SLMSG 


[FORMAT codel [,COMP-code] 
[,HALTcode| [,StJBH-code] [.SEVcodfi] 
[,DEF-code] (,OPN0-Y/N] I.OPNI Y/N) 
[,OPN2-Y/N[ [,0PN3-Y/J^i [TLEN-number ] 
[.FADR address] 



FORMAT-code specifies the type and length of the system 
log parameter list. The valid code values and their meaning 
follow; 



Code 


Length of 


List 


Format of List 


A 


7 bytes 




F DCC HH 


B 


9 bytes 




F DCCHH II 


C 


10 bytes 




F DCCHH L AA 


D 


12 bytes 




F DCC HH II L AA 



SEV-code specifies the severity which conditions the seiec 
tion of the default (DEF) option operant) This entiy cor 
responds to the severity code entry in the NOHALI state 
ment. If the severity code specified in the NOHALT state 
ment is less than the value specified in this entry, t[ie halt 
will be issued. Valid entries (from lowest to highest sevoniy) 
are 1, 2, 4, and 8. If this operand is oitiitled, a soveiity of 
8 is assumed. 



DEF code specifies tlie default option to select when execut- 
ing in unattended mode. Valid entries aie N, 0, 1, 2, and 
3; if this operand is not specified, IM (none) is assumed. 



OPNO-Y/N specifies whether option is allowed, if Y 
(yes) is entered, option is allowed; if N (no) is entered oi 
if this operand is f)mitteu, or)tion is not allowed. 



0PN1 Y/N specifies whether option 1 is allowed. If Y is 
entered, option 1 is allowed; if N (no) is entered or if ihi^. 
operand is omitted option 1 is not allowed. 



where; F and D are flag bytes 
CC is the component ID 
HH is the message ID 
O is the option indicator (this is determined 

by the settings of operands OPNO, OPN 1 , 

OPN2,andOPN3) 
II is the sub-halt ID 
L is the length of the text 
AA is the address of the text 

If this operand is omitted, FORMAT-B is assun-ied. 



0PN2'Y/N specifies whether option 2 is allowed. If Y 
(yes) is entered, option 2 is allowed; if N (no) is entered oi 
if this operand is omitted, oinion 2 is not r.ilr.weci 



0PN3 Y/N specifies whether option 3 is allowed. If Y (yes) 
is specified, option 3 is allowed; if N (no) is si)ecified or if 
this operand is omitted, option 3 is rrot allov./e,i. 

Note: If Ciption 3 is allovi/ed, control will rif.'t in: ictiiinetl 
to youi program. 
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TLEN-number specifies the text length. This entry (L), 
which is a decimal entry f--om 1 to 107, is required if 
FORIVIAT-CorD is specified. 



TADR-address specifies the leftmost byte of the text 
address. This operand (AA) is required if FORMAT-C or D 
is specified. 



Generate the Linkage to the System Log ($LOG) 

This macro instruction generates the linkage required to use 
the system log function, and checks the response returned. 
The $LOGD macro instruction must be used with this 
macro instruction, to establish offsets in the system log 
parameter list. 

If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $LOG macro instruction. 

The format of the $LOG macro instruction is: 



Name] 



SLOG 



[LIST-address] l.OPNO-addressI 
[,0PN1 -address] ],OPN2-addres: 



LIST-address specifies the address of the leftmost byte of 
the system log parameter list. If this operand is not speci- 
fied, the address of the parameter list is assumed to be in 
register 2. 



OPNO-address specifies the address of the routine that 
should receive control if option is taken. If this operand 
is not specified, no check is made for a response of 0. You 
would use this operand only if the SLMSG macro was used 
to generate the parameter list. 



OPNI -address specifies the address of the routine that 
should receive control if option 1 is the response. If this 
operand is not specified, no check is made for a response of 
1. You would use this operand only if the SLMSG macro 
was used to generate the parameter list. 



0PN2-address specifies the address of the routine that should 
receive control if option 2 is taken. If this operand is not 
specified, no check is made for a response of 2. You would 
use this operand only if the SLMSG macro was used to gen- 
erate the parameter list. 



Generate Displacements for System Log ($LOGDj 

This macro instruction generates the field labels and offsets 
for the system log parameter lists. To avoid duplicate labels, 
you should use this macro instruction ofily once in a program. 



The format of the $LOG macro i 



nstruction is: 



SLOGD 



General SCP Support 

The general SCP macro instructions allow you lo iirovide 
linkage to system functions by communicating with the 
Model 15 system control program. 



Rollout/Roll in Linkage i$ROLL) 

This macro applies to Program Number 5704-SC1 only. 

You use SROLL to interrupt (roll out) the current program 
so that another program can be executed. When the second 
program is finished, the first program is reinstated (rolled 
in) and continues executing. 

Once rollout is initiated, the CRT/Keyboard becomes the 
system input device until otherwise specified by the user 
or until the interrupted program is rolled in. 

When using rollout, you should follow these procedures: 

1 , Note the following restrictions: 

a. A program using SROLL can execute in either 
partition, but will acknowledge the rollout request 
only when running in partition 1, 

b. A program using SROLL must be so defined to the 
linkage editor using the ATTR p,'irameter in the 
OPTIONS statement (see IBM System/3 Overlay 
Linkage Editor Reference Manual, GC21-7561), 

c. If the interrupting program also recognizes rollout 
requests, these requests will be ignored, 

d. The same I/O devices are available to the interrupt- 
ing program as were available to the original pro- 
gram with exception of tape units, 

e. Whenever an interrupting program shares the same 
disk files as a rolled-out program, only reading 
and updating are allowed by the two programs. 
Loading and additions are not allowed, 
updating are allowed by the two programs. Load- 
ing and additions are not allowed. 



12 



2. Issue the $ROLL macro instruction: 

The coding generated by the $ROLL macro instruc- 
tion determines whether rollout has been requested 
by entering the ROLLOUT operator control com- 
mand. If rollout has not been requested, the current 
program continues executing. If the request is pend- 
ing the rollout routines are called. Rollout performs 
the following steps: 

a. Places the current program (program being exe- 
cuted and the current contents of the scheduler 
work area on disk. 

b. Allows a new program or procedure to be run in 
place of the current program. 

c. Reloads the original program and restores the 
previous contents of the scheduler work area 
and passes control to the point where the orig- 
inal program was interrupted. 



The format of the $ROLL macro instruction is: 



[Name] 


SROLL 


[INDEX-1/21 



INDEX-1 /2 specifies which register can be used in the 
macro instruction. If this operand is omitted, register 2 is 
used. 



If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $FIND macro instruction. 

The format of the $FIND macro instruction is: 



Name] $FIND NAME-module[,FIND-address] [,PACK-P/S1 



NAME-module provides the name of the module to be 
found. Only names of object modules (0 modules) can 
be entered here. 



FIND-address specifies the label that becomes the address 
of a 12-byte parameter list built by the generated code. 
Initially the parameter list contains input to the supervisor. 
After execution, it contains the directory entry of the 
module. The format and contents of the parameter list 
after execution are shown in Figure 5. If this operand is 
not specified, a macro label is generated. 



PACK-P/S specifies the program disk pack (P) or the system 
disk pack (S) to be searched. If this operand is not specified, 
P is assumed. 



Load a Module ($LOAD) 



Find a Directory Entry ($FINDj 

A load module must be in the object library. Specific infor- 
mation must be obtained from the module's object library 
directory entry before a load or fetch can be performed. 
There are two ways you can locate a load module and ob- 
tain the information: 

• Issue a $FIND before issuing a $LOAD, Form II. The 
information obtained during the find is used during the 
load operation. 

• Issue a load with find (SLOAD, Form I), a fetch 
($FTCH) or a fetch to address ($XCTL). These func- 
tions perform the find operation as part of their normal 
functions. 

The $FIND macro instruction searches the object library 
directory for the requested module name and returns the 
directory entry in the parameter list. 



This macro instruction loads a module into storage at the 
address you specify. Controi is returned after the module 
has been loaded. You may then pass control to the module 
at the specified address. If you will need to use the data in 
register 2 at a later time, you should save the contents of 
that register before issuing the SLOAD macro instruction. 
Two forms of this macro can be used: load with find and 
load only. 

Load with Find (Form I) 

The load with find macro instruction locates the module 
and loads it into main storage. 

The format of this macro instruction is: 



[Name] 


SLOAD 


NAME-module name [, FIND-address) 
[ LOAD-2/address] [,USE-R/NR1 
[,PLIST-address] [,PACK-_P/S) 
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Entry 



Disk Address 

I\iuml)ei o< 
text sectors 

Link edit 
address 

Displacement 
of RLDs 

Entry point 
address 

Storage si/i? 

Attributes 



Level 



Number 
of Bytes 



? 



Displace- 
ment 



1 



/ 
8 
A 



B 



Description 



Cylinder/sector address of tl^ie module. 

Type O-Sector length of the module in hexadecimal 
Type H- Category of routine 

Hexadecimal storage address at which the module was lirtkage edited. 
See note 2. 

Number of bytes, in hexadecimal, into the first sector containing RLDs, 
of the first relocation directory (R LD) entry of the module. 

Hexadecimal storage address at which program execution begins (with- 
out RLDs). 

Amount of storage (in sectors) required to execute the program. 



Byte 1: 
Bit 

1 
2 



4 
5 
6 
7 

Byte 2: 
Bit 



4 
5 



1 = Permanent entry 

= Temporary entry 

1 = Inquiry program 

1 = Rollout-evoking program (5704-SC1 only) 
1 = External buffers (if byte 2, bit 1 = 1) 

(5704-SC2only) 
1 = Must run in dedicated environment 

(5704-SC1 only) 

Reserved (5704-SC2 only) 
1 = Requires source information 
1 = Deferred mounting allowed 
1 = PTF applied 
1 -^ Overlay object program 



1 - The system input device must be dedicated to 

this program 
1 = Checkpoint/Restart program 
1 = External buffers (if byte 1, bit 2 = 1) (5704-SC2 only) 

See note 1 
1 = This program will access the source file directly 
1 = Macro processor is allowed (5704-SCl only) 
1 = Model 15D program (5704-SC2 only) 
1 = This IS a privileged program 
1 == This program requires that a new load address be 

calculated at load time to place it in main storage 

beyond its own program common region 
1 = 3340 data management (5704-SCl only) 

Reserved (5704-SC2 only) 
Memory resident overlays 



F^elease version of this entry. 



Notes: 

1. For 5704-SC2 the checkpoint/restart and external buffer attributes are mutually exclusive. 

2. For 5704-SC2, if the entry has the attributes for external buffers, the low-order byte of the link edited address 
contains the number of sectors minus 1 . 



Figure 5. Find Parameter List Description 
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Number 


Displace- 




Entry 


of Bytes 


ment 


Description 


Disk Address 


2 


1 


Cylinder/sector address of the module in hexadecimal. See note 1 . 


Number of 








text sectors 


1 


2 


Sector length of the module, in hexadecimal. 


Link edited 








address 


2 


4 


Storage address at which the module was linkage edited. See note 2. 


Displacement 






Hexadecimal displacement, in bytes, into the first sector containing RLDs, 


of RLDs 


1 


5 


of the first relocation directory (RLD) entry of the module. 


Relocated entry 








point address 


2 


7 


Storage address at which program execution begins, after resolving RLDs. 


Load address 


2 


9 


Address at which the requested module is loaded. 


Notes: 






1 . If a directory entry was not found on a load witfi find. 


the first byte contains a character 0. 


2. For5704-SC2 


, if the entry has the attributes for external buffers, the low-order byte of the link edited address 


contains the number of sectors minus 1 . 





Figure 6. Find Parameter List after Load Execution 
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NAME-module name provides the name of the module to 
be loaded and is required. Only O modules can be 
specified. 



FIND-address becomes the address of the parameter list 
passed to the find routine. The parameter list is generated 
by the macro processor. After execution of the load, this 
parameter list contains the modified entry for the module 
as shown in Figure 6. 



LOAD-2/address specifies the address where the module 
is to be loaded into main storage. The 2 indicates that the 
address is in register 2; the address is the symbolic address 
where the module is to be loaded. If this operand is not 
specified, 2 is assumed. 



USE-R/NR indicates whether the code generated by the 
macro instruction is to be reusable (R) or nonreusable (NR). 
If the operand is not specified, NR is assumed. 

You can reuse the generated code to load the same module 
more than one time, or to load different modules. If you 
wish to load different modules using the same generated 
code, you should also specify the PLIST operand. 



Load Only (Form II j 

The load-only macro instruction loads a module previously 
found by the $FIND macro instruction. The format of 
this macro instruction is: 



[Name] 



$LOAD 



FIND-address [,L0AD-2/address] 
[,PACK^/S] 



FIND-address is the address used in the previous $FIND 
macro instruction. It identifies the directory entry of the 
module in main storage. After execution of the load, this 
address points to the directory entry of the module as 
shown in Figure 6. 



LOAD-2 /address specifies the address where the module 
is to be loaded in main storage. The 2 indicates that the 
address is in register 2; the address is the symbolic address 
where the module is to be loaded. If this operand is not 
specified, 2 is assumed. 



^/4C/C-^/S specifies the program disk pack (P) or system 
disk pack (S) containing the requested module. If this 
operand is not specified, P is assumed. 



PLIST-address is used only when the generated code is 
reusable. The address specified identifies the leftmost 
byte of a parameter list passed to the load routine. To 
load a different module using the same generated code, 
you must update the parameter list to indicate the desired 
module. Figure 7 shows the format and contents of the 
parameter list. 



PACK-P/S specifies the program disk pack (P) or the 
system disk pack (S) containing the requested module. 
If this operand is not specified, P is assumed. 



Load a Module and Pass Control ($FTCH) 

The fetch macro instruction (SFTCH) finds a module in 
the directory, loads the module into main storage, and 
passes control to it. Your program does not regain control. 
When a module is fetched into main storage, the relocation 
factor is added, as necessary, to the module's link edit 
address. This determines the location in main storage 
where the module is loaded. The module receives control 
at its entry point. 



Entry 



Module Type 

Module Name 

FE 

Load Address 



Number 
of Bytes 



Displace- 
ment 




6 
7 
9 



Description 



Must contain O to indicate an object module. 

The name of the module to be loaded. 

X'FE' 

The address at which the module is to be loaded. 



Figure 7. Load Parameter List Description 
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If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $FTCH macro instruction. 

The format of the $FTCH macro instruction is: 



[Na 



SFTCH 



Name-module name[,PACK-P/S] 



Generate a Translate Parameter List ($TRL) 

This macro instruction generates a parameter list needed 
by the Model 15 Translate routine. This list is called via 
the $TRAN macro instruction. $TRL does not generate 
executable code. Figure 8 shows the format of the 
translate parameter list. 



NAME-module name specifies the object module to be 
fetched into main storage. The name must be the same as 
the name in the directory entry. 



PACK-P/S specifies the program disk pack (P) or the 
system disk pack (S) containing the requested module. If 
this operand is not specified, P is assumed. 



Load a Module and Exchange Control ($XCTL) 

This macro instruction finds a module in the directory, 
loads the module into main storage at the address you ' 
specify, and passes control to it. Control is not returned 
to your program. As with the $FTCH macro instruction 
relocation factors are resolved, and control is passed to 
the entry point of the program. 

The format of the $XCTL macro instruction is: 



[Name] 



SXCTL 



NAME-module name[,L0AD-2/address] 
[,PACK-P/S] 



NAME-module name specifies the name of the module to 
be loaded and given control. The module must be an O 
module. 



Translate Routine Operation 

To use the Model 15 translate routine, you must provide a 
translate area. The format of the area is: 

Byte Field Description 

Byte contents used to determine whether a 
character is to be translated. 

1 Byte contents are substituted for characters 
that are not to be translated. 

2-257 256-byte translate table. 

The translate routine processes a field, specified by the 
$TRAN macro instruction, one byte at a time. 

The translate table must be constructed so that the displace 
ment (from the beginning of the table) of the translated 
representation of a character is equal to the hexadecimal 
representation of the untranslated character, (For example, 
if you want to translate X'CV to X'41', you could 
construct a translate table in which the value at displace- 
ment X'Cr in the table is X'41'.) 

The contents of the byte at a given displacement are com- 
pared with the contents of the first byte in the translate 
area (byte 0). If an equal compare results, the character is 
considered to be invalid and the following actions are 
performed: 



LOAD-2/address specifies the address where the module 
is to be loaded in main storage. The 2 indicates that the 
address is in register 2; the address is the symbolic address 
where the module is to be loaded. If this operand is not 
specified, 2 is assumed. 



PACK-P/S specifies the program disk pack (P) or the 
system disk pack (S) containing the requested module. 
If this operand is not specified, P is assumed. 



• The completion code in the parameter list is set to indi- 
cate that an invalid character was detected. 

• The hexadecimal value in the second byte of the trans- 
late area (byte 1 ) is substituted for the original character. 

If an unequal compare results, the hexadecimal value in the 
translate table is substituted for the original character. 

The format of the $TRL macro instruction is: 



[Name] 



$TRL 



TO-address, FROM -address, LEN-n umber, 
TRT-address 
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TO-address specifies the symbolic address of the first byte 
of the data to which the translated data will be moved. 



FROM-address specifies the symbolic address of the first 
byte of the data field to be translated. This address may 
be the same as the address specified in the TO operand. 



LEN-number specifies the decimal length of the FROM 
field. 



TRT-address specifies the symbolic address of the first 
byte of the translate area. 

All four operands are required. 



Generate a Translate Table ($TRTB) 

This macro instruction generates an EBCDIC to ASCII or 
an ASCII to EBCDIC translate table. The table is generated 
in the format required by the $TRL macro instruction, and 
can be addressed by $TRL when you translate data. 

The format of the STRTB macro instruction is; 



[Name] 



STRTB 



[CODE-E/A] l,HEX-hexl 



CODE-E/A specifies whether the character code of the 
data to be translated is EBCDIC (E) or ASCI I (A). If this 
operand is omitted, EBCDIC (E) is assumed. If CODE-E 
is specified, $TRTB generates a 258-byte table; if CODE-A 
is specified, $TRTB generates a 130-byte table. 

Note: If you specify CODE-A, you may want to specify 
DC 128XL1'FF' after the STRTB macro instruction to 
allow for invalid ASCII characters. 



Generate an Interface to the Translate Routine ($TRANj 

This macro instruction generates an interface to the Model 
15 translate routine. After the translate routine has 
finished, control is returned to your program with a com- 
pletion code in the translate routine parameter list. The 
address of the parameter list is in register 1. You should 
check the completion code to see if any characters that 
are not to be translated were encountered. 

The format of the $TRAN macro instruction is: 



[Name] 


$TRAN 


[TRL-address] 



TRL-address specifies the symbolic address of the translate 
parameter list. If this operand is not entered, the address 
is assumed to be in register 1 . See Figure 8 for a description 
of the parameter list. 



Field 
Length 



Field Description 



Address of the translate area (your program must 

define the translate area) 

FROM field address, for translation 

TO field address for translation 

Number of bytes to translate 

Completion code: 

X'OO' —translation complete, no errors 
X'FF' —invalid character detected 



Figure 8. Translate Parameter List 

Snap Dump Main Storage ($SNAPj 

This macro instruction provides an interface with the non- 
terminating system storage dump routine. You must 
specify a dump identifier and the limits of the area to be 
dumped. The contents of the specified main storage area 
are put on the 1403 printer. Output from the dump 
routine consists of: 



HEX-hex specifies the hexadecimal pattern with which to 
replace any invalid characters found during translation. If 
the HEX operand is not specified, the replacement char- 
acter is X'3F' for EBCDIC or X'1 A' for ASCI I. 



• The specified dump identifier. 

• The contents of register 1 (XR 1 ), register 2 (XR2), the 
Instruction Address Register (lAR), the Program Mode 
Register (PMR), the Address Recall Register (ARR), and 
the Local Storage Register (LSR). 

• The contents of the specified main storage area. 

Control is returned to the next sequential instruction in 
your program. 



18 



The format of the $SNAP rnacfo iiistiuction is: 



[Name] 



SSNAP 



ID-hfx,f 



START-adrirRss.END addres 



ID-hex specifies a 2- byte hexadecimal number to be used 
as the dump identifier. 



START-address specifies the symbolic address of the low- 
storage limit of the area to t)e dumped. 



END-address specifies the symbolic address of the high- 
storage limit of the area to be dumped. 

All three operands are required. 



DATE-Y/N specifies whether a date field is to be generated. 
If this operand is not entered, N (no) is assumed. If the 
$TOD macro instruction is used in your program, Y (yes) 
must be entered. If DATE-Y is specified, use of the $SIT 
macro instruction destroys the date in the timer lOB. 



Set Interval Timer ($SITj 

This macro instruction sets the interval timer to cause a 
timer interrupt after the specified amount of time has 
elapsed. Before issuing this macro instruction you must 
place the desired interval in bytes 2-7 of the timer 108. 
When the interval is set, byte 8 in the timer 108 is set to 
X'OO'. When the interval is expired, byte 8 is set to X'40', 

The format of the $SIT macro instruction is: 



Obtain System Date ($DA TE) 

This macro instruction generates the code necessary to 
retrieve the system date and place it at a specified location 
in your program. 

If you will need to use the data in register 2 at a later 
time, you should save the contents of that register before 
issuing the$DATE macro instruction. 



[Name] 


$SIT 


[lOB-namel [,TYPE-DEC/BIN/TU/TODl 
[,ITYPE-REAL/WAIT/TASKI 



lOBname specifies the name of the timer 108 generated by 
the $TI08 macro instruction. I f this operand is omitted, 
the address of the lOB is assumed to be in register 2. 



The format of the $DATE macro, instructii 



Name] $DATE [LABEL address] 



TYPE-DEC/BIN /TU/TOD specifies the forrTiat of the time 
interval in the lOB. You must establish the time interval 
in bytes 2-7 of the lOB before issuing the $SIT macro in 
struction. The valid time interval formats are: 



LABEL address indicates the adiiiess o! Ilie leftiiiost byte 
of a six-byte area in which you want the system date 
placed. If this operand is not specifiRd, ihe afldiess at 
which you want the date to be placer! is assumed to be in 
register 2. 



Generate Timer lOB ($TIOB) 

This macro instruction generates an lOB lot the interval 
timer. $1 lOB must be used if you use SSI T , Sf^ IT, or 
STOD in your program. The format of the Um-'r lOB is 
shown in Appendix C: Input/Output Blocks^ 

The format of the $TIOB macro instruction is: 



[Name] 



$TIOB 



[DATE-Y/N] 



• DEC: The time interval is the amoirnt of time in decimal 
that is to elapse before tfie timer interrupt. The time 
interval is a six-byte decimal number specifying hours, 
minutes, and seconds (HHMMSS). 

• BIN: The time interval is a 32-bit binary number speci- 
fying the number of seconds that are to elapse before the 
timer interrupt. The binary value must be right-justified 
in fjytes 4-7 of the lOB field. 

• TU: The time interval is a 32-bit binary number speci- 
fying the number of timer units that are to elapse before 
the timer interrupt. One timer unit is 3.33 milliseconds. 
The binary value must be right-justified in bytes 4-7 of 
the 108 field. 

• TOD: The time interval is the actual time of day when 
the timer interrupt is to occur. The time is a six-byte 
decimal number specifying the hour, minute and second 
(HHIVIMSS). 



If this operand is omitted, DEC is assumed. 



Macro Instruction Slatements 
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ITYPE-REAL/WAIT/TASK specifies the type of interval 
to be timed. The types of time intervals are: 

• REAL: The timer decrements the time interval continu- 
ously for all types of processing. 

• WAIT: The program issuing the $SIT macro instruction 
is placed in a wait state for the specified time interval. 
When the time has expired, control returns to the instruc- 
tion following the $SIT macro instruction. 

• TASK: The timer decrements the time interval only 
while the task issuing the $SIT macro instruction is run- 
ning. 

If this operand is omitted, REAL is assumed. 



Return Time and Date ($TODj 

This macro instruction returns the time of day and the 
system date to the program. The time of day is returned in 
bytes 2-7 of the timer lOB, the system date in the next six 
bytes. DATE-Y must be specified in the $TIOB macro 
instruction if the $TOD macro instruction is used. 

The format of the $TOD macro instruction is: 



[Name] $TOD 



[lOB-name] [,REF-Y/I\!I [,TYPE-DEC/BIN/TU 



lOB-name specifies the name of the timer lOB generated 
by the $TIOB macro instruction. If this operand is omitted, 
the address of the lOB is assumed to be in register 2. 



REF-Y/N specifies whether the macro instruction is being 
issued from the transient area or a program partition. Y 
(yes) indicates the macro instruction is issued by a transient 
that must be refreshed; N (no) indicates it is issued from a 
program partition. If this operand is omitted, N (no) is 
assumed. 



TYPE-DEC/BIN/TU specifies how the time is to be returned 
in the timer lOB. The valid formats are: 

• DEC: The time returned is a six-byte decimal number 
indicating the time in hours, minutes and seconds 
(HHMMSS). 

• BIN: The time returned is a 32-bit binary number indi- 
cating the time in seconds. The binary number is right- 
justified in bytes 4-7 of the lOB field. 

• TU: The time returned is a 32-bit binary number indicat- 
ing the time in timer units. One timer unit is 3.33 milli- 
seconds. The binary number is right-justified in bytes 
4-7 of the lOB field. 

If this operand is omitted, DEC is assumed. 



Return Interval Time ($RIT) 

This macro instruction returns the remaining amount of 
time in a time interval or cancels an unexpired time interval. 
The remaining time is returned in bytes 2-7 of the timer 
lOB established by the $TIOB macro instruction. The time 
interval must have been set by the $SIT macro instruction 
and is returned in the format specified in that macro instruc- 
tion. 

The format of the $R IT macro instruction is: 



[Name] $RIT 





[lOB-name] [,CANCEL-Y/I\[) 



u 



lOB-name specifies the name of the timer lOB generated by 
the $TIOB macro instruction. If this operand is omitted, 
the address of the lOB is assumed to be in register 2. 

CANCEL-Y/N specifies whether the remaining time in the 
interval is to be cancelled. If this operand is omitted, N (no) 
is assumed. 



End-of-Job ($EOJ) 

The SEOJ macro instruction generates the linkage required 
to execute the end of job routine. The option to perform 
an immediate cancel or a controlled cancel is provided. 

The format of the SEOJ macro instruction is: 



[Name] 


SEOJ 


[CANCEL-NORM AL/IMIVIED/CONTR LI 
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CANCEL- NORMAL /IMMED/CONTRL specifies the 
action that the system should take as it terminates the 
program. If this operand is omitted or if NORMAL is 
specified and the system is in HALT mode, an end of job 
step message is issued and job processing terminates in the 
partition; if NOHALT mode is in effect, no message is 
issued and job processing continues. 
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If your program specifies CANCEL-IMMED or CANCEL- 
CONTRL and it is a step of a job or a procedure in a 
chained procedure, all remaining steps in the job or all 
remaining procedures in the chained procedure are cancelled. 
Also, EJ or ES is displayed regardless of the status of the 
system halt mode, and job processing in that partition 
terminates. 



If IMMED is specified, the disposition of files depends upon 
the function being performed; 

• New files being created will not be retained 

• Old files being deleted will be retained 

• Old files being added to will not reflect the additions 

• Old files being updated will reflect the updates made 
prior to the point at which this $EOJ macro instruction 
was executed 

• Add files (except for consecutive) will reflect additions 
if file sharing (5704-SC2 only). 

If CONTRL is specified, the files being used by your pro- 
gram reflect all activity which took place up to the point 
the $EOJ macro instruction was executed. 



If either CANCEL-IMMED or CANCEL CONTR L is speci- 
fied, the input stream is flushed in the following manner: 

• If you are executing in job mode on a system on which 
input spooling is active, job processing in the partition 
resumes with the next job on the job input queue. 

• If you are executing in job mode on a system on which 
input spooling is not active, the job stream in the system 
reader is flushed until a JOB statement or a slash period 
(/.) statement is encountered. 

• If you are executing in step mode, the input stream will 
be flushed until a JOB, LOAD, CALL, slash period (/.) 
or slash ampersand (/&) statement is encountered. 
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INPUT/OUTPUT SUPPORT MACROS 



The input/output support macro instructions provide access 
to devices without requiring that you wnte extensi.t-; rou- 
tines to perform each function. The input/output sijpport 
macro instructions are divided into eight groups. 

1. General macro instructions are used with e,;: .atv,ce 
types. The following macros are ir trns gr .,i.. 



Teleprocessing only 



$ALOC 

$CKL ; 

$CHK > 

$CLOS 

SCOIVIN 

$DTFO 

$OPEN 



Card macro instructions support card devices. The 
following macros are in this group: 

SDTFC 
$GPC 
SGETC 
$PUTC 

Printer macro instructions support printer ae.'ices. 
The following macros are in this group. 

$DTFP 
$PUTP 

Disk macro instructions provide SL,jport arm nnkage 
to disk data management. The toliowmg niduros are 
in this group: 

SDTFD 

$GETD 

$IOBD 

$IOED 

$PUTD 

SRDD 

$WAIT 

$WRTD 



Tape macro insTiuciioiis provide support and linkage 
tc> tape data iiianagement. The foiiowing macros are 
m this group: 

SCTLT 
SDTFT 
SGETT 
SPUTT 

SRCT 

SWRTT 

SWTT 

Device independent macio instructions provide sup- 
purt and linkage to device independent data manage- 
ment. The following macros are in this group: 

SDTFI 
SGETI 
SPUTI 

CRT macro instructions support CRT devices. The 
tuiiowing .macros are in this group: 

SCQEP 

SDTFS 

SGETS 

SPFKT 

SPFKY 

SPGS 

SPUTS 

3741 macro instructions provide support and linkage 
to 3741 data management. The following macros 
are in this group; 

SDTFK 
SGETK 
SPUTK 



General I/O Support 

The general I/O support macro instructions are used with 
both unit record, tape, and disk devices. The normal 
sequence for using these macro instructions is: 



1 . SALOC to allocate the device to your program 
partition. 

2. SOPEN to prepare the file or device for use. 

3. l,/0 operations and any processing required. 

4. SCLOS to prepare the file and/or device for job 
termination. 
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Allocate Space l$ALOC) 

The routines called by the $ALOC macro instruction allo- 
cate unit record input/output devices and space on disk and 
tape devices. These routines check to ensure that: 

• The system supports the requested device. 

• The device requested is available to the requesting 
program. 

• The LOCATION parameter of the OCL file statement 
is valid. 

• The correct disk pack is mounted and space is available 
to the calling program. 

• The number of disk, tape, and device independent 
DTFs in the calling program is limited as follows: 

- 5704-SC1-Thelimitis40. 

- 5704-SC2-The limit is 192 with at least a 10K 
partition. The limit is 128 with only an 8K 
partition. 

For 5704-SC2, not all 192 disk and tape DTFs may be 
allocated in a single call to allocate. The maximum 
number of tape and/or disk DTFs in a single chain is 
as follows: 

- If all are disk, the maximum is 165. 

- If all are tape, the maximum is 148. 

- For combinations of disk and tape, the maximum 
varies between 148 and 165. To determine whether 
or not the DTFs can be allocated in a single call to 
allocate, multiply the number of disk DTFs by 17 
and multiply the number of tape DTFs by 19. If 
the sum of the above two numbers is not greater 
than 2816, the DTFs may be allocated in a single 
call. 

If the DTFs cannot all be allocated in a single call, make 
two DTF chains and two calls to allocate. 



An allocate request requires that pre-open DTFs be sup- 
plied as input to the routine. For a description of DTFs, 
see Define the File for Card ($DTFC), Define the File for 
Disk ($DTFD), Define the File for Device Independent 
($DTFIj, Define the File for Printer ($DTFPj, Define the 
File for CRT ($DTFS), Define the File for Tape ($DTFT), 
and Define the File for 3741 ($DTFK). When the allocate 
request is for a disk, a tape device, or a device independent 
file, OCL file statements are also required. More than one 
DTF can be allocated at one time by chaining the DTFs. 
To chain DTFs, you must enter the address of the next 
DTF in the DTF you are building. The last DTF in a chain 
has X'FFFF' entered in place of the address. If your 
program operates as an interrupt handler, such as a binary 
synchronous communications program, all DTFs in the 
program should be chained together and allocated in one 
operation. When an error condition occurs, the allocate 
routine calls halt/syslog to display the proper halt code. 

Note that if you will need to use the data in register 2 at a 
later time, you should save the contents of that register 
before issuing the $ALOC macro instruction. 

The following output is produced when control is returned 
to your program. 



• The contents of register 1 are restored. 

• The format-1 labels and configuration record are up- 
dated. 

• For a non-disk or non-tape DTF, bit 1 in the rightmost 
byte of the attribute bytes of the post-open DTF is set 
on to indicate device allocation. 

• For a device independent DTF, the device code (dis- 
placement in the DTF - $DFDEV) is altered to 
indicate the appropriate device. 



The address of the first DTF allocated is returned in 
register 2. 



• The correct tape input file is mounted, or the tape label 
is written on the output file, and that the tape is posi- 
tioned at the beginning of the file. 



Note: If you are using telecommunications, $ALOC must 
not be issued while a telecommunications operation is in 
process. 
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The format of the SALOC macro instruction is: 



[Name] 


SALOC 


[DTF -address] 



DTF-address specifies the address of the high-order byte of 
the DTF being allocated. If this operand is not entered, the 
address of the DTF is assumed to be in register 2. 



Prepare An I/O Device ($OPEN) 

This macro instruction prepares an input/output file for 
data transfer. The file to be prepared (opened) must pre- 
viously have been allocated by using the allocate macro 
instruction. Depending on the device, one or more of the 
following functions are performed for each file opened. 

• The post-open DTF is formatted (see Figure 9). 

• Pre-open DTF information is preserved in the format-1 
label as required. 

• Input/output buffers, index buffers, and lOBs are 
formatted. 

• Buffers are initialized as required. 

• Disk file share area is prepared as required (5704-SC2 
only). 

• Cards are positioned at the wait station for card output 
files. 

• The index area on disk for indexed files and the data 
area on disk for direct files are formatted as required. 

• Diagnostics are performed to ensure that; 

— The access method and the file organization are 
compatible. 

— The volume and file are mounted on the correct disk 
or tape drive. 

— Share attributes are checked for disk files (5704-SC2 
only). 

Note: More than one DTF can be opened at one time by 
chaining the DTFs. To chain DTFs, you must enter the 
address of the next DTF in the DTF you are building. 
The last DTF in a chain has X'FFFF' entered in place of 
the address. See $DTFC, $DTFD, $DTFI, $DTFP, $DTFS, 
SDTFT, and $DTFK. 



Pre-Open Conditions 


Post-Open Conditions 


1. Unformatted DTFs are 


1. 


Formatted DTFs are 


present for output 




created. 


flies. 








2. 


I/O buffers, lOBs.and 


2. The I/O buffer is in the 




various work areas are 


unformatted mode. 




formatted. 




3. 


A bit is set on in the 
DTF attribute bytes to 
indicate an opened file. 



Figure 9. Comparison of Pre-Open and Post -Open DTFs and 
Data Areas 



Input: The pre-open DTF and format-1 label are input to 
the open routine. Before the open macro instruction is 
issued, you must be sure to have the device allocated by 
previously issuing the allocate macro instruction. Also, if 
you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $OPEN macro instruction. You must also consider the 
following in preparing the DTF: 

• The disk access method must be compatible with the 
disk file organization of the file being opened. 

• The access method must be compatible with the access 
method of the same file opened in the other program 
level or for an inquiry program (see Rollout). 

• The record length, block length, and key length must be 
specified correctly. 

• The file must have share specified if it is to be shared 
for disk files (5704-SC2 only). 



Output: The open routine returns control to your program 
when the requested file has been opened. The following 
output is produced: 

• The contents of register 1 are restored. 

• The format-1 labels are updated. 

• Bit 7 in the rightmost attribute byte in the post-open 
DTF is set on to indicate the file has been opened. 

• The device code (displacement in the DTF - $DFDEV) 
is altered to indicate the unit on which the disk or tape 
file resides. 



• The buffers are initialized. 
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• The address of the last DTF opened is returned in 
register 2. 

• The file share area is updated for disk files with share 
specified (5704-SC2 only). 



For a description of the checklist entries, see Figure 10. 



The format of the $OPEN macro instruct! 



on is: 



[Name] 



SOPEN 



[DTF address] 



DTF-address specifies the address of the leftmost byte of 
the DTF for the file to be opened. If this operand is not 
entered, it is assumed that the address is in register 2. 

Note: Any files opened during a job should be closed 
before the job ends ($CLOS macro). For 5704-SC2 only, 
any open files will be closed during EOJ processing (nor- ' 
mal or abnormal). Therefore, DTFs must be available at 
this time. Any disk files opened using file sharing must 
be closed to perform required actions on the file share 
area. 



Generate a Checklist ($CKL) 

This macro instruction creates an entry for a checklist It 
does not generate executable code. A checklist identifies 
DTFs to be checked for I/O completion, or determines 
whether the PF9 key has been pressed. Two kinds of DTFs 
can be identified in the checklist: 

• Binary Synchronous Communications (BSC) DTFs 

• Dummy DTFs (15-byte DTFs used to check for the PF9 
key) 

All the checklist entries that are to be tested by the same 
$CHK macro instruction must be issued consecutively. 
The same DTF may be in the list more than once. The 
checklist entries that are generated are contiguous in main 
storage. You can then issue the $CHK macro instruction to 
test the entire list, by specifying the first entry in the list; 
or l^fgin testing anywhere in the list, by specifying the 
label of one of the later entries. 

Note: The address you specify in the $CHK macro instruc- 
tion identifies the beginning of the check operation. Any 
entries occurring earlier in the list are ignored in that 
operation. 



Disp 



Field Description 



1-2 



Flag byte: 

X'80'— Skip this entry 

X'40'-Request key (PF Key 9) should be checked 
X'20'-This is the last entry in the checklist 
X'lO'-Return control to the user if no I/O com- 
pletion is found (significant only in the 
first entry of a checklist) 
X'08'— Code destroyed 
X'04'— Program function key not available 

Address of the DTF for this entry 



Figure 10. Checklist Format 

For a description of BSC, see IBM System/3 Multiline/ 
Multipoint Binary Synchronous Communications Reference 
Manual. GC21-7573. 

The format of the $CKL macro instruction is: 



[Name] 



$CKL 



DTF-address [,SKIP-Y/N_] [,REQK-Y/J\I] 
[,RTN-Y/N] [,LAST-Y/N] 



DTF-address specifies the symbolic address of the first byte 
of the DTF for which this entry is being created. A dummy 
DTF, 15 bytes in length, is required to check if the PF9 key 
was pressed. Displacement X'OO' in this DTF should con- 
tain a X'10' and a completion code will be returned at dis- 
placement X'OE'. 



SKIP-Y/N specifies whether this entry should be skipped 
when the checklist is scanned. If this operand is omitted, 
N (no) is assumed. If Y is specified, you must update the 
checklist entry before you can check the DTF specified in 
this macro instruction. You can access the skip indicator 
in the entry by using the name specified on the macro in- 
struction. 



/?£Q/C-///\/ specifies whether the check routine (see index 
entry $CHK macro instruction) should check if the PF9 
key has been pressed. Whenever you want the check rou- 
tine to check for a PF9 request, you must include a dummy 
DTF in the checklist and specify REQK-Y for that entry. 
REQK-Y is ignored if it is specified for a DTF that is not 
a dummy PF9 DTF (a device code of X'10' in the first 
byte of a DTF denotes a dummy PF9 DTF). If the operator 
pressed the PF9 key, a completion code of X'50' is posted 
at displacement X'OE' of the dummy DTF. 



Macro Instruction Statements 25 



RTN-Y/N specifies whether you want control returned to 
your program even if no I/O operation is complete. This 
operand is valid only for the first entry in the check list. If 
this operand is not entered, N (no) is assumed. 



LAST-Y/N specifies whether this is the last entry in the 
checklist. LAST-Y (yes) must be specified for the last 
entry. If this operand is omitted, N (no) is assumed. 



CKL-address specifies the symbolic address of the first entry 
in the checklist. You can also begin at a subsequent point 
in the checklist by specifying the symbolic address of a 
later entry. If this operand is omitted, the address is 
assumed to be in register 2. 

Note: The address you specify identifies the beginning of 
the check operation. Any entries occurring earlier in the 
list are ignored in that operation. 



Check for I/O Completion ($CHK) 

This macro instruction generates the linkage required to use 
the check routine. You must issue the $CHK macro instruc- 
tion for each BSC get, put, read, write, or online test 
request. For a description of BSC macro instructions, see 
IBM System/3 Multiline/Multipoint Binary Synchronous 
Communications Reference Manual, GC21-7573. 

If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $CHK macro instruction. 



Check Routine Operation 



Prepare a Device for Termination ($CLOS) 

The close macro instruction prepares a device for job termi- 
nation. The routine returns post-open DTFs to their pre- 
open state and updates file labels to reflect the current file 
status. For devices other than disk or tape, only the entries 
related to the requested functions are restored. If you will 
need to use the data in register 2 at a later time, you 
should save the contents of that register before issuing the 
$CLOS macro instruction. 



Input to the close routine consists of the post-open DTF 
and the format-1 labels. The allocate and open macro in- 
structions must have previously been issued. 



Note: When using this macro, the user program must 
equate $PARM to 2. 

The check routine tests for completion of an I/O operation 
by examining the DTFs identified in the checklist — see 
Generate a Checklist ($CKL). If an I/O operation is com- 
plete, the completion code is set in the DTF, and the ad- 
dress of the DTF is returned in register 2 to the calling 
program. No subsequent DTFs in the list are tested. 

When no I/O completion is found by the end of the check- 
list, control is returned to your program with the address 
of the last DTF in the list register 2 if: 

Each entry in the list is inactive, closed, or has the skip 
indicator on (a completion code of X'57'). 

RTN-Y was specified in the $CKL macro instruction 
that created the first entry in the checklist (a comple- 
tion code of X'56'). 

The format of the $CHK macro instruction is: 



[Name] 


$CHK 


[CKL-address) 



Output created by $CLOS is returned to your program 
when control is returned. The output consists of: 

• The contents of register 1 restored. 

• The post-open DTFs reinitialized to the pre-open state. 

• Any pending operations for unit record devices 
performed. 

• The format-1 label for disk updated to indicate current 
file status. 

• The buffer contents scheduled for disk or tape output 
and disk update operations written. 

• The data and index written to disk, and an indicator set 
if key sorting is required at end-of-job for output files 
and file additions. 

• Tape trailer labels read or written. 

• The file share area is cleared or updated for the disk 
file specified as share. 



26 



Note: More than one DTF can be closed af one tfrne bv 
chaining the DTFs. To chain DTFs, each DTF to be cio^-ed 
must contain the address of the next DTF m the chain The 
last DTF in a chain has X'FFFF' entereti m nidce of tho 
address. 



The format of the $CLOS macro instruction is. 



INamel SCLOS IDTFaddrRss 



D7T-aoWress specifies the address of t :■ if'tmost nytc 
the DTF to be closed. If this operand !■; ^ fir entered t' 
address is assumed to be in register 2. 



Generate DTF Offsets fSDTFO) 

This macro defines the DTF labels, offsets 'ie^rl contents. 
and field lengths for all devices and access methods si:p;>or 
ed for the Model 15. To avoid duplicate label .. tn.c marr.-. 
instruction should be used only once n- "ac;- rn-jnim; vo',, 
should also set the operands to indicate jnv devices ycu 
plan to use in the program. 
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MFCM y ''■J specifies whether labels are to be generated for 
the MFCM. If this operand is not specified, N (no) is 
assumed. 



D374 7-Y'l\l specifies whether labels are to be generated for 
the 3741. If this operand is not specified, N(no) is assumed. 



D2501 y 'V specifies whether labels are to be generated for 
the 250' 'f th<s operand is not entered, N (no) is assumed. 



D1442 y N specifies whether labels are to be generated for 
the 1442 If this operand is not entered, N (no) is assumed. 



D1403 ^ •'>.• sDecit;es whether labels are to be generated for 
the 140.3 if this operand is not entered, N (no) is assumed. 



D3284 ' A/ specifies whether labels are to be generated for 
the 3284 If this operand is not entered, N (no) is assumed. 



The format of the SDTFO 



macro inst'ncti 



Name] 



SDTFO 



IDISK-Y/Ni [.TAPE Y,N| | ,IML).Y:Ai^, 
[.MFCUY'Nl f.MFC^^'v.N: ,D3,4i v 
[,02501 Y/r£) (.01442 ]}<_; ;,D14.:i3Y, 
[,D3284-Y/NJ |,CRT-Y;JM_i [.ALL Y'^i 
i.FiELCYiMi 



DISK-Y/N specifies whether label-, a-" *n li!- (ienprat. ; 
disk devices. If this operand is not ente^eu H fno' is 
assumed. 



TAPE-Y/N specifies whether labels arc t,. 
tape device. If this operand is not en'ptp- 
assumed. 



CRT'V A/ .riecifies whether labels are to be generated for 
the CRT ;' this operand is not entered, N (no) is assumed. 



ALL -V'A soecifies whether labels are to be generated for all 
devices stinported. If this operand is not entered, N (no) is 
assumed 



FIELD '*■' iV specifies whether to generate the labels which 
define tfv. contents for a DTF field. If this operand is not 

specifi':: Y (yes! ^s assumed. 



COMMOr-J Euuares i$COMN) 



INDY/N specifies whether labels a'" t.: •-.^- 
independent device. |f this opovanH 15 i.;t 
is assumed. 



This n-a^n nstriiction generates equates for various labels 
and va! ;•■■,. such as riigister equates, which may be used in 
the pioqram. This macro instruction is not required. 

The formar of the SCOMN macro instruction is: 



MFCU-Y/N specifies whether labels an- :> dc qen.pr,;)Ti-d fnr 
the MFCU. If this operand is not entoreri N \nn) is dssu-Tied. 



t( .•■:^,1^ 
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Card Device Support 

This section describes the macro instructions that support 
card devices. The following functions are provided: 



NIOB-number is a required operand specifying the number 
of lOBs associated w/ith this DTF. This entry must have a 
value of 1 or 2. 



• Build a pre-open DTF for card device and assign its off- 
sets. 

• Build the interface required to read/punch/print records 
using a card device. 



DEV-code specifies the card device desired. The possible 
values for code are MFCU1, MFCU2, MFCMI, I\/1FCI\/12, 
1442, and 2501. If this operand is omitted, MFCUI is 
assumed. 



The DTF provides information to the card device data man- 
agement routines that perform input/output operations. 



Define the File for Card ($DTFC) 

The DTF provides information needed to allocate, open, 
and access a card device. This macro instruction generates 
the code that builds a card DTF. 

The format of the $DTFC macro instruction is: 



[Name] 


$DTFC 


lOBA-address, NIOB-number 
[, DEV-code] 

[,UP-maskl [,CHN -address) 
[,RCAD-address] [,OPC-code] 
[,DEFER-Y/N] [,CARDI-Y/N] 
[,PRINT4-Y/N] [,FEED-Y/n1 
[,STACKR-number] [,READA-address] 
[,PUNCHA-address] [,PRINTA-address] 
[,READL-number] [,PUNCHL-number] 
[.PRINTL-number] [,PRHEAD-mask] 
[,ALIGN-Y/N] 



UP-mask specifies the mask to test the eight external 
indicators. The code for the UP-mask must be specified 
as 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would enter UP-10010101. The UP-mask is compared 
to the external indicators set on by the SWITCH statement 
for conditionally opening files. If the bits that are on in the 
UP-mask are also on in the external indicators set on by the 
SWITCH statement, the file will be opened. If the UP-mask 
is all zeroes or not used, the file will be unconditionally 
opened. 

Note: Information on setting external indicators (SWITCH 
statement) can be found in the IBM System/3 IVIodel 15 
System Control Programming Reference Manual (for 
Program Number 5704-SC1), GC21-5077, and in the 
IBM System/3 Model 15 System Control Programming 
Concepts and Reference Manual (for Program Number 
5704-SC2),GC21-5162. 



lOBA-address is a required operand specifying the address 
of the leftmost byte of the first lOB. The area identified 
by this operand must be large enough to contain one lOB 
for single buffering or two lOBs for double buffering 
(specified via the operand NIOB-2). The sizes for each 
card lOB are: 

2501 - 25 bytes 
MFCU -29 bytes 
1442 -29 bytes 
MFCM -31 bytes 
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CHN-address indicates tiie address of the next DTF in the 
chain of DTFs. If there is no DTF chain or if this is the 
last DTF in the chain, the operand should be omitted 
(X'FFFF' is assumed). 



FEED-Y/N specifies whether or not to perform a feed oper- 
ation after a 1442 punch operation. If Y (yes) is specified 
or if this operand is omitted, a feed is performed after the 
punch operation. 



RCAD-address specifies the leftmost byte of the logical 
record for ^,n output operation. If this operand is not 
entered, a value of X'OOOO' is assumed; this value must be 
updated before an output operation is performed. If this 
operand is specified foi an input operation, the value speci- 
fied will not be used, and this operand will be modified by 
the card data management module to contain the address of 
the card that was read. 



STACK R-number specifies the stacker to be used for this 
card operation. This operand is not used with the 2501 . If 
this operand is not specified, the byte containing the 
stacker number will be set to X'OO'. 

Note: If this operand is zero the following occurs: stacker 
one is used if the card originated in hopper 1 ; the highest 
number stacker is used if the card originated in hopper 2. 



OPC-code defines the operation code for the DTF. A list 
of the possible codes and their meanings are: 



Code 



Meaning 



RD 


Read 






PU 


Punch 






PR 


Print 






PP 


Punch and print 


J 


Not allowed for 


RPU 


Read and punch 


( 


MFCM1 


RPR 


Read and print 




or 


RPP 


Read, punch, and 


print ' 


l\/IFCIVI2 



If this operand is not specified, the operation code for a 
feed is set. 



DEFER-Y/N is used only with output operations to the 
MFCM and IVIFCU. This operand enables you to print one 
record on a card and punch a different record in the same 
card. The $DTFC, $PUTC, and $GPC macro instructions 
can be used to specify this process. For $GPC or $PUTC, 
you must first issue that macro instruction for either a 
print or a punch with DEFER-Y. You then modify the 
logical record as needed to a different format and issue that 
macro instruction for tiie remaining operation with 
DEFER-N. Both operations are then performed. If this 
operand is not specified, N (no) is assumed. 



CARDI-Y/N specifies whether or not to perform a read 
card image operation on the 1442 or 2b01. If N (no) is 
specified or if this operand is omitted, a card image read is 
not performed. 



PRINT4-Y/N specifies whether to print three or four tiers 
for a print request from the MFCU. Y (yes) indicates that 
four tiers shouid be printed, if this operand is omitted or if 
N (no) is specified, three tiers are printed. 



READA-address specifies the address (at a 128-byte boun- 
dary) of the buffer used for read operations. If double buf- 
fering is used, both buffers must be on 128-byte bound- 
aries, and the two buffers must be contiguous in main stor- 
age. You must specify this operand if you plan to use this 
DTF for a read operation. 

PUNCHA-address specifies the address (at a 128-byte boun- 
dary) of the buffer used for punch operations on the 1442, 
MFCU, or MFCM. If double buffering is used, both buffers 
must be on 128-byte boundaries, and the two buffers must 
be contiguous in storage. You must specify this operand 
if you plan to use this DTF for a punch operation. 

PRINTA-address specifies the address (at a 256-byte boun- 
dary) of the buffer used for print operations on the MFCM 
or the MFCU. For the MFCM, the buffer size must be 64 
bytes times the highest print head used. If double buffering 
is used, both print buffers must be contiguous in main stor- 
age. For the MFCU, the buffer size must be 1 28 bytes for 
single buffering and 256 bytes for double buffering. If two 
DTFs are being used for printing from both hoppers of the 
MFCU, the operation must be single buffered and the DTFs 
must use the same 256-byte print area. You must specify 
this operand if you plan to use this DTF for a print operation. 

READL-number specifies the number of card columns to 
read. This operand should be used with the MFCM or 2501 
only. If this operand is not specified, the maximum value 
(80) is assumed. 



PUNCH Lnumber specifies the number of card columns to 
punch. This operand should be used with the MFCM or 
1442 only. If this operand is not specified, the maxiinum 
value (80) is assumed. 
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PRINTL-number specifies the number of columns to print 
per liead on tlie IVIFCIVI. If this operand is not specified, the 
maximum value (64) is assumed. 

PRHEAD-mask defines the print heads selected for the 
MFCM. The mask must be specified as an eight-bit field. 
If this operand is omitted, the current setting of the print 
head selection byte in the DTF is not modified. The fol- 
lowing table shows the meaning of each bit. 

Bit Meaning 

and 1 = Unused, must be zero 

2 = 1 Select print head six 

3 = 1 Select print head five 

4 = 1 Select print head four 

5 = 1 Select print head three 

6 = 1 Select print head two 

7 = 1 Select print head one 



The code generated by this macro instruction gives control 
to the data management routine; the routine completes 
execution and returns control to the generated code. If 
the ERR or EOF operand is specified, the generated code 
tests the completion code returned by data management 
and branches to your routine. 

The format of the $GETC macro instruction is: 



[Name] 


SGETC 


(DEV-code! [.DTF-address] (,EOF-address] 
[,ERR-address] [,OPC-Y/N] 
[,READL-number] [,CARDI-Y/N] 
[,STACKR-numtaer] 



DEV-code specifies the appropriate device. One of the 
following codes must be used: MFCU, MFCM, 1442, or 
2501. If this operand is not specified, default is made to 
MFCU. 



ALIGN-Y/N specifies whether to print in a special format 
on the MFCM. If Y (yes) is specified, the first 64 charac- 
ters are printed with print head 1 and the next 16 charac- 
ters are printed right-justified with print head 2. If N (no) 
is specified or if this operand is not entered, printing occurs 
in the normal manner. 



Construct a Card Get Interface ($GETCj 



DTF-address indicates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 



EOF-address specifies the address in your program that re- 
ceives control when the end-of-file is detected. If this oper- 
and is not supplied, no code is generated to check for the 
end-of-file condition. 



The $GETC macro instruction generates the interface re- 
quired to communicate with card data management when a 
record is being read from a card device. To use this instruc- 
tion, you must construct a card DTF for the file and use 
the $DTFO macro instruction to establish the offsets in 
the DTF. If you will need to use the data in register 2 at a 
later time, you should save the contents of that register be- 
fore issuing the $GETC instruction. You must also provide 
the labels for the necessary data management routines, via 
EXTRN statements in your program. The names of the 
data management routines for each device are: 



ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code. 

Note: If ERR or EOF addresses are not specified, you 
should check the return code in your program to determine 
the outcome of the operation. 



Module Name 


Device 


$$MFRD 


MFCU 


$$MMRD 


MFCM 


$$ARFF 


1442 


$SARRD 


2501 



OPC-Y/N indicates whether or not the read operation code 
should be altered in the DTF. If Y (yes) is specified, the 
read/punch/print bit in the operation code is set to indicate 
a read. If N (no) is specified or if this operand is omitted, 
read/punch/print bit in the operation code is not modified. 



READL-number specifies the number of columns to read 
from the MFCM or 2501 . If this operand is not specified, 
the DTF remains unchanged. 
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CARlJI ', /N bpucifids whether to perform a read card image 
opeiatiun on tile 1442 or 2501. If Y (yes) is specified, the 
Cciul ihidije read Ijit in tlie operation code is set on. If N 
(no) is ^}^■v^i\ad, tiie card image bit in the operation code is 
se( off. I f this operand is omitted, the status of the card 
ihirttje read bit in the operation code is not modified. 



OPC-code specifies the operation code to be used, i f tliis 
operand is not specified, the status ot the print/punch bits 
in the operation code is not changed. \'diid codes are as 
follows: 



Code 



Moaning 



SiACKH /iiiiiibi.-i specifies the stacker to be used for hold- 
iiiy tiie cards after tlie read operation. This operand is not 
used with the 2501 . If this operand is not given, the value 
in the U"rF is not clianged. 



PU Punch 

PR Piint 

PP Print and punch (This code is not aliowed 

forMFCM.) 



Coi-niniCL d Curd Put Interface ($PUTC) 

fills iiiacrc) insttuction generates the interface needed to 
communicate with card data management when punching 
and/oi |ji lilting a card file. You must provide a DTP for 
the tile and ii.',(; tlie SDTFO macro instruction to establish 
the offsets in the fJTF. You must also provide, through 
EX rR(\,' statements in your program, the labels of the card 
data management modules necessary to perform the output 
operation. Tiie names of the data management routines for 
eav;h (ie\'K.e aie: 



Module Name 



Device 



S$MFPP MFCU 

$$MMPP MFCM 

$$ARFF 1442 

If you need to use the data in register 2 at a later time, you 
should save the contents of that register before issuing the 
$PIITC instruction. 

The code generated by this macro instruction gives control 
to the data management routine. The routine completes 
execution and returns control to the generated code. If the 
ERR operand is specified, the generated code checks the 
completion code for errors and branches to your error rou- 
tine if errors occurred. 

The format ot the $PUTC macro instruction is: 



Name) 



$PUTC 



[DEV-code] [,DTF-addressi [,OPC-codeJ 
[,DEFER-Y/N] [,PRINT4-Y/N) 
[,FEED-Y/N1 [,STACKR-number] 
[.PUNCH L-number] [,PRINTL-number] 
[,PRHEAD-mask] [,ERR-address] 



DEV-code specifies the appropriate device. One of the fol- 
lowing codes must be used: MFCU, MFCM, or 1442. If 
this operand is not specified, default is made to MFCU. 



DEFER-Y/N specifies whetlier tlie print and/u- punch ojjer 
ation should be deferred. It Y (yes) is specirief!, tiuj defer 
operation bit in the operatii,n oodd is er oi.if N (no) is 
specified, the defer opciat or; Liil in tlie os.eiatiun cod,; is 
set off. If this operand is not specified, t e status ot i; v: 
defer bit is not cfianged. 



PRINT4-Y/N specifies whether to print on four tiers o1 the 
MFCU card. If Y (yes) is specified, tfie fourth tier print bit 
in the operation code is set or;; if N (no) is specified, ttie 
fourth tier print bit is set off If this oper.-jiKi is omitted, 
the status of the fourth tier print bit in the operation code 
is not changed. 



FEED-Y/N specifies whether to perform a feed operation 
following the 1442 punch operation. Y (yes) indicates that 
a feed should occur after the punch; if N (no) is entered, a 
feed is not performed after the punch operation. If this 
operand is omitted, the status of the feed/iio feed bit in the 
DTP is not changed. 



STACK R-nurnber specifies the stacker to be used for this 
operation. If this operand is omitted, the value of the 
stacker-select byte in tlie DTP is not ch.anged. 



PUNCH L-number specifies the number of columns to punch. 
If this operand is omitted, the value in the punch-length 
byte is not changed. This operand should be used with the 
MFCM or 1442 only. 



PRINTL-number indicates the number of columns to be 
printed by each head on the MFCM, If this operand is 
omitted, the value in the print-length byte is not changed. 



DTF address specifies the address of the leftmost byte of 
the DTF for this file. If this operand is not entered, the 
address is assLimed to be in register 2. 
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PRHEAD-mask defines the MFCM print heads selected. 
The masl< must be specified as an eight bit field. If this 
operand is omitted, the current setting of the print head 
selection byte in the DTF is not modified. The following 
chart shows the meaning of each bit: 



The format of the $GPC macro instruction is; 



Bit 



Meaning 



9 and 1=0 Unused, must be zero 

2 = 1 Select print head six 

3 = 1 Select print head five 

4 = 1 Select print head four 

5 = 1 Select print head three 

6 = 1 Select print head two 

7 = 1 Select print head one 



ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code, and you should check the return code in 
your program to determine the outcome of the operation. 



Construct an Interface for Reading, Punching, and Printing 
Cards ($GPC) 

The $GPC macro instruction generates the interface required 
to communicate with card data management when a record 
is being read, punched, and/or printed on a card device. To 
use this macro instruction, you must construct a card DTF 
for the file and use the $DTFO macro instruction to estab- 
lish the offsets in the DTF. If you will need to use the data 
in register 2 at a later time, you should save the contents of 
that register before issuing the $GPC instruction. You must 
also provide labels for the necessary data management rout- 
ines via EXTRN statements in your program. The name of 
the data management routine for each device is: 



Module Name 


Device 


SSIVIFFF 


MFCU 


S$MMFF 


MFCM 


$$ARFF 


1442 



The code generated by this macro instruction gives control 
to the data management routine; the routine completes 
execution and returns control to the generated code. If the 
ERR or EOF operand is specified, the generated code tests 
the completion code returned by data management and 
branches to your routine. 



[Name] 


$GPC 


[DEV-code] [,DTF-address] [,OPC-code] 
[,DEFER-Y/Nj [,CARD1-Y/N] 
[,PRINT4-Y/N] [,FEED-Y/N] 
[.STACKR-number] [,READL-number] 
[.PUNCH L-number] [.PRINTL-number] 
[,PRHEAD-maskl [,EOF-address] 
[, ERR-address] 



DEV-code specifies the card device desired. The possible 
valuesfor this code are: MFCU, MFCM, and 1442. If this 
operand is not specified, MFCU is the default value. 



DTF-address specifies the address of the leftmost byte of 
the DTF for this file. If this operand is not entered, the 
address is assumed to be in register 2. 



OPC-code specifies the operation code to be used. Valid 
codes and their meanings are: 



Code Meaning 

RD Readonly 

PU Punch only 

PR Print only 

PP Punch and print 

RPU Read and punch 

RPR Read and print 

RPP Read, punch, and print 



Not allowed 
for MFCM 



If this operand is not specified, the status of the read/ 
punch/print bits in the operation code is not changed. 



DEFER-Y/N specifies whether to defer the punch and/or 
print request. If N (no) is specified the request is not de- 
ferred; if this operand is not specified the status of the 
defer bit in the DTF is not changed. 



CARDI-Y/N specifies whether to perform a read card image 
operation on the 1442 or 2501 . If N (no) is specified or if 
this operand is omitted, a card-image read is not performed. 



PRINT4-Y/N specifies whether to print three or four tiers 
for a print request from the MFCU. Y (yes) indicates that 
four tiers should be printed; if this operand is omitted or if 
N (no) is specified, three tiers are printed. 
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FEED-Y/N specifies whether or not to perform a feed 
operation after a 1442 punch operation. If Y (yes) is 
specified or if this operand is omitted, a feed is performed 
after the punch operation. 



STACKR-number specifies the stacker to be used for this 
card operation. This operand is not used with the 2501 . If 
this operand is not specified, the byte containing the stacl<er 
number is set to X'OO'. 



READL-number specifies the number of card columns to 
read. This operand should be used with the IVIFCM or 
2501 only. If this operand is not specified, the default value 
is 80. 



PUNCHL-number specifies the number of card columns to 
punch. This operand should be used with the IVIFCIVI or 
1442 only. If this operand is not specified, the default value 
is 80. 



PRINTL-number specifies the number of columns to print 
per head on the MFCIVi. If this operand is not specified, the 
default value is 64. 



ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error, if this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code. 

Note: If ERR or EOF addresses are not specified, you 
should check the return code in your program to determine 
the outcome of the operation. 

Printer Support 

This section describes the macro instructions that support 
the printers. The following functions are provided: 

• Build a pre-open DTF for a printer and assign its offsets. 
The DTF provides information to printer data manage- 
ment routines that perform input/output operations. 

• Build the interface needed to print data. 



Define the File for Printer ($DTFP) 

The DTF provides information needed to allocate, open, 
and access a printer. This macro instruction generates the 
code that builds the printer DTF. 



PRHEAD-masl< defines the print heads selected on the 
MFCM. The mask must be specified as an eight bit field. 
If this operand is omitted, the current setting of the print 
head selection byte in the DTF is not modified. The fol- 
lowing table shows the meaning of each bit: 



The format of the $DTFP macro instruction is: 



Bit 



Meaning 



Oand1=0 Unused, must be zero 

2 = 1 Select print head six 

3 = 1 Select print head five 

4 = 1 Select print head four 

5 = 1 Select print head three 
6=1 Select print head two 
7 = 1 Select print head one 



[Name] 


SDTFP 


RCAD-address,IOBA-address,IOAA-address, 
OVFL-number,PAGE-number [,DEV-code] 
[,UP-mask] [HUC-Y/N] [,CHN-address] 
[,PRINT-Y/N] [,SKIPB-numberl [SPACEB- 
number] [,SKIPA-number] [,SPACEA-number] 
[,RECL-number] 



RCAD-address is a required operand which gives the address 
of the leftmost byte of the logical record. 



lOBA-address is a required operand specifying the address 
of the leftmost byte of the lOB. The lOB will be 50 bytes 
long. 



EOF-address specifies the address in your program that 
receives control when the end-of-file is detected. If this 
operand is not supplied, no code is generated to check for 
the end-of-file condition. 



lOAA-address is a required operand which specifies the 
address of the leftmost byte of the I/O area. For the 1403, 
this address must define the I/O area as beginning on a 124- 
byte boundary. The length of the I/O area must be: 



• 132 bytes for the 1403 printer 

• The record length +7 for the 3284 printer. 
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OVFL number specifies tl'ie line number on the printer 
after which the overflow completion code will be returned, 
if this operand is not specified, default is made to 6 lines 
less than the number specified for the PAGE operand. 



SPACEB-number specifies the number of lines (maximum 
of 3 lines) to space before the print operation. If this 
operand is not entered, the default value is zero. 



PAGE-number specifies the number of lines to print per 
page. If this operaiuJ is not specified, default is made to the 
system value for the number of lines per page. 



SKIPA-number specifies the line to be skipped to after the 
print operation. If this operand is not specified, the default 
value is zero. 



DEV code specifies the printer desired. The possible values 
for this code are 1403 and 3284. If this operand is not 
specified, 1403 is assumed. 



UP-mask specifies the mask to test the eight external 
indicators. The code for the UP-mask must be specified 
as 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would entei UP-10010101. The UP-mask is compared 
to the external indicators set on by the SWITCH statement 
for conditionally opening files. If the bits that are on in the 
UP-mask are also on in the external indicators set on by the 
SWITCH statement, the file will be opened. If the UP-mask 
is all zeroes or not used, the file will be unconditionally 
opened. 

Note: Information on setting external indicators (SWITCH 
statement) can be found in the IBM System/3 Model 15 
System Control Programming Reference Manual for Pro- 
gram Number 5704-SC1, GC21-5077 and IBM System /3 
Model 15 System Control Programming Concepts and 
Reference Manual for Program Number 5704-SC2, GC21 - 
5162. 



SPACEA-number specifies the number of lines to space (0, 
1, 2, or 3) after the print operation. If this operand is not 
specified, it defaults to a value of zero if DEV-1403 is speci- 
fied or to a value of one if DE\/-3284 is specified. A space 
after of zero is not allowed for the 3284 printer, and, if 
zero is specified, the operand defaults to a space after of 
one. 



RECL-number specifies the length of the line to be printed. 
If this operand is omitted, default is 132 positions. 



Construct a Printer Put Interface ($PUTP) 

This macro instruction generates the interface needed to 
communicate with printer data management. You must 
provide a DTP for the file and use the $DTFO macro 
instruction to establish the offsets in the DTP. You must 
also provide, through an EXTRN statement in your pro- 
gram, the label $$LPRT, for the 1403, or $$LPMP, for the 
3284. (These labels are for the printer data management 
module necessary to perform the printer output opera- 
tion.) 



HUC-Y/N specifies whether to halt if an unprintable charac- 
ter is detected. If N (no) is specified or if this operand is 
omitted, no halt occurs. 



CHN-address indicates the address of the next DTP in the 
chain of DTFs. If there is no DTP chain or if this is the 
last DTP in a chain, this operand should be omitted (a 
value of X'PPFF' is assumed). 



If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $PUTP macro instruction. 

The code generated by this macro instruction gives control 
to the data management routine. The routine completes 
execution and returns control to the generated code. If the 
ERR operand is specified, the generated code checks the 
completion code for errors and branches to your error 
routine if errors occurred. 



PRINT -Y/N specifies wfieihc-r to perform a print and a skip 
or space or only a skip or space. Default is N (no), mean- 
ing that a print is not performed. 



SKIPB-number specifies the line to skip to before the print 
operation. If this operand is not entered, the default value 
is zero. 



The format of the $PUTP macro instruction is: 



[Name] 


$PUTP 


[DEV-code] [,DTF-address] [,PRINT-Y/N] 
[,SKIPB-number] [.SPACEB-number] 
[SKIPA-number] [.SPACEA-number] 
[.ERF^-address] [,OVFL-address] 
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DEV-code specifies the printer device desiied. The possible 
values for this code are 1403 and 3284. If this operand is 
not specified, 1403 is the default value. 



DTF-address specifies the address of the leftmost byte of 
the DTF for this file. If this operand is not entered, the 
address is assumed to be in register 2. 



PRINT-Y/N specifies whether to perfrom a print and a skip 
or space or only a skip or space. If this operand is not 
specified, the DTF remains unchanged. 



Disk Device Support 

This section describes the macro instructions that support 
disk devices. The following functions are provided; 

• Build a pre-open DTF for disk GET/PUT operations 
and assign its offsets. 

• Build an input/output block (lOB) for disk read/write 
operations and assign its offsets. 

• Build the interfaces required to get input records from a 
disk device via a get or a read. 



SKIPB-number specifies the line to skip to before the print 
operation. If this operand is not entered, the DTF remains 
unchanged. 



Build the interfaces required to put output records to a 
disk device via a put or a write. 

Build the interface to wait for disk completion. 



SPACEB-number specifies the number of lines to space be- 
fore the print operation. If this operand is not entered, the 
DTF remains unchanged. 



SKIPA-number specifies the line to be skipped to after the 
print operation. If this operand is not entered, the DTF 
remains unchanged. 



The disk DTFs provide information to the disk data man- 
agement, and the disk lOBs provide information to the 
input/output supervisor routines that perform the input 
or output operations. These operations are provided 
through the disk support macro instructions. 

The IBM 3340 Direct Access Storage Facility attaches to 
System/3 Models 15B, 15C,and 15D. Also, the IBM 3344 
Direct Access Storage attaches to System/3 Model 15D. 



SPACEA-number specifies the number of lines to space after 
the print operation. If this operand is not entered, the DTF 
remains unchanged. 



ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code, and you should check the return code in 
your program to determine the outcome of the operation. 



OVFL-address specifies the address in your program that 
should receive control if page overflow occurs. 



Certain areas on the 3340 and 3344 disks are treated as 
5444 disks. These areas, known as simulation areas, are 
used for program libraries and can also be used for data 
files. These areas cannot contain multivolume or indexed 
files. The remainder of the disk space, known as main 
data areas, can only be used for data files. 

Reference in this manual to 5444, 5445, and 3340 are to 
be interpreted according to which disk storage device(s) 
is attached to the system. The following table should be 
used to determine the meaning of the reference: 

References to D3 and D4 Q-numbers in this manual may be 
replaced with D31 and D41 for 5704-SC2. 
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Model 15A 


Model15Band 


Model 15D 


Reference 


Meaning 


15C Meaning 


Meaning 


5444 


5444 Disk 


Simulation 


Simulation 




Storage 


area on 


area on 3340 




Drive 


3340 


or 3344 


5445 


5445 Disk 


Main data 


Main data 




Storage 


area on 


area on 3340 






3340 


or 3344 


3340 


Not 


Main data 


Main data 




applicable 


area on 3340 


area on 3340 
or 3344 



The format of the $DTFD macro instruction is: 



For Program Number 5704-SC2, there are certain restric- 
tions on where the DTFs and associated fields can be located 
relative to 40K (X'EOOO') in the user partition: 

• DTFs must be located such that the entire DTF resides 
at an address less than 40K for batch disk files speci- 
fied as SHARE-YES and for CCP disk files. 

• For the following disk access methods where SHARE- 
YES is specified, the high add key and the high prime 
key areas (ADKEY parameter) must be located 
completely below 40K: 

- Indexed output add 

- Indexed random input and add 

- Indexed random input, update and add 

• If a disk file is specified with external buffers, then 
the following must be located completely below 
40K: 

- The DTFs 

- The index lOBs (10 parameter) 

- The master track index (MSTX parameter) 

- The space for the multivolume extent table (10 
parameter, M, and M, definitions) 



Define the File for Disk ($DTFD) 

The DTF provides information needed to allocate, open, 
and access a file on the disk device. This macro instruction 
generates the code that builds the disk DTF. See Appendix 
B: Define the File Control Blocks for a description of the 
pre-open and post-open disk DTFs. 



[Name] 


$DTFD 


AC-code,RECL-number,NAME-filename, 
BLKL-number,IO-address 
[,DISK-5444/5445/3340] 
[.UP-mask] [,BUFN0-1/21 [,MVF-N/Y] 
[,LIM-N/Y] [,ORD-N/Y] [,BIN-N/Y] 
[,CHN-address] [.RCAD-address] 
[,ENT-number] (,MVFN-number] 
[,KEYL-number] [,KEYD-number] 
[,KEYA-address] [.MVFT-address] 
[, MSTX -address] [,IBLKL-number] 
[,ADKEY-address] [,EOVK-address] 
[,SHR-Y/N]' [,EXTBUF-Y/N]' 



' These parameters are valid only for Program Number 5704-SC2. 

AC-code specifies the access method used for the file. This 
operand Is required. The codes and their meanings are as 
follows: 

Code Access Method 

CA Consecutive add 

CG Consecutive get 

CO Consecutive output 

CD Consecutive update 

DG Direct get 

DO Direct output 

DU Direct update 

lA Indexed add 

10 Indexed output 

IS Indexed sequential get 

ISA Indexed sequential add 

ISL Indexed sequential input with limits 

ISU Indexed sequential update 

ISUA Indexed sequential update and add 

ISUL Indexed sequential input update with limits 

IR Indexed random get 

IRA Indexed random add 

IRU Indexed random update 

IRUA Indexed random update and add 



RECL-number specifies the decimal length of the logical 
record. This operand must be specified. 



NAME-flle name specifies the name of the file. The name 
must be eight characters or less in length. This operand 
must be specified. 
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BLKL-number specifies the number of bytes in trie outter. 
The minimum number can be deterniineu as ioliows. except 
for the access methods listed on the ioliowiny pages, for 
which the minimum number of bytes is 256. 

• If tne record length is less trian o< -quai io 256 jnd 
evenly divisible into 256, ^he ouiter Itnyth is 256 

• If the record length is greater than 256 and a muitip'e 
of 256, the buffer length is equal to the record langtf:. 

• if tne record length is not t'veiny :iiv-:;;;i.- iiiin 256 and 
no! a muhiple of 256. the biiHpr lengih ■.'■, me multiple 
of 256 that is next higher than the leco, o length plus 
255. 
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Now: These buffer lengths are minimum lengths. Larger 
lengths may be specified, but must be in multiples of 256. 

The foliovviing access methods can always operate in a mini- 

rnufii of a 256-liyte buffer- 

Consecutive output 

Consecutive add 

Consecutive output multivolutne 

Consecutive add muitivolume 

Consecutive input 

Consecutive input muitivolume 

Indexed output 

indexed output muitivolume 



• If the record length is an odd muitipk- of 128, the t)uffei 
should be the record length plus 128. 



Access Method 



Consecutive, Direct 
Indexed Output 



indexed Fiandom Input, or 
Indexed Random Input and 
Update 



inriexed Random input and 
.Add, or Indexed Random 
Input, Update, and Add 



Indexed Add 
(without input) 

Indexed Sequential Input, 
or Indexed Sequential 
Input and Update 

Indexed Sequential 
Input and Add, or 
Indexed Sequentid: Inpu! 
Update, and Add 

Indexed Ot-quentoi/lirnits 
input, o;' indexerj 
Sequent ia!.U,!rri Its inpi^t 
and Update 



>0~address provides tfie address of the leftmost byte of an 
area in main storage allocated to contain all buffers and 
iOBs tor the access method. This operand must be speci- 
fied Tlie amount of main storage required is shown in the 
following chart. 



Formuia 



EXTBUr-Y 
iSpacs in l./O area) 



Formula for External Buffers on 
Option Statement 



>BUI--tgO 



30) timys BlsFNO 
'J 06 * 60 i 



1 1 'Ties 
;,r MVt' 



!2S8 ' iOi 



iBLK> • :■ 

+ hi 1 , wtK-';' 

M; u.i: ,i?igl';^ voium(^ :i!ps 

M^ 84 - KtYL i-" rnult!- 



^ .;0) - 2':)6 tinipj ;Bl.K L • 
30 + M , . 'A'hprp 

V!_ - ti If"! ;;i!Upi: vg^'jitu' fi 

>/0:...::ip !|ii'S 

(BLICl ! 30! '- '258 i 301 
+ V56 '••ne; Hi-. Kl • JO 



'■ B L. K I 
IBLKl. 



30, - 256 M.Tics 



2 times t'Bi KL ^ 301 -r 
2 times (256 iirnes IBLKl 
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limes BUF-NO + KEYL 


' .';- 


t'TlVF 


/2 


- !>.,'; , v-jhcrc 


V' .. 


for s-nglp volume files 


1-/1. 


84 + KhYL toi miiiii- 




volume tilps ib704-SC1) 


t,/i 


1 12 -r KFYL ior multi- 




volume isles (5704-SC2J 



-;a4 t M , . where 
M • 9 for single voluciu- tiles 
M;. !80 i- KFYL for mui':- 
^oium^; files 
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BLKL times BUFNO 



BLKL + 256 times BUFNO 



BLKL + 512 



2 times BLKL + 512 
+ (256 times IBLKL) 



BLKL +512-1- (256 times IBLKL) 



BLKL + (256 times IBLKL) 



2 times BLKL + 2 times (256 
times IBLKL) 



BLKL + 256 + 256 (BLKL) 
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D/S K-5444/5445/3340 spec\f\es whether the disk device is 
the 5444 Disk Storage Drive, the 5445 Disk Storage, or the 
3340 Direct Access Storage Facility. If this operand is not 
specified, 5444 is assumed. 



BIN-N/Y is specified only with the direct output, direct get, 
and direct update access methods. Y (yes) indicates direct 
binary relative record numbers; N (no) indicates direct deci- 
mal relative record numbers. If this operand is omitted, N 
is assumed. 



UP-mask specifies the mask to test the eight external 
indicators. The code for the UP-mask must be specified 
as 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would enter UP-10010101. The UP-mask is compared 
to the external indicators set on by the SWITCH statement 
for conditionally opening files. If the bits that are on in the 
UP-mask are also on in the external indicators set on by the 
SWITCH statement, the file will be opened. If the UP-mask 
is all zeroes or not used, the file will be unconditionally 
opened. 

Note: Information on setting external indicators (SWITCH 
statement) can be found in the IBM System/3 Model 15 
System Control Programmming Reference Manual (for 
Program Number 5704-SC1), GC21-5077, and in the IBM 
System/3 Model 15 Control Programming Concepts and 
Reference Manual (for Program Number 5704-SC2), 
GC21-5162. 



BUFNO-1/2 allows you to specify either one or two buffers 
for the file. You can use two buffers only with consecutive 
access methods and indexed output. All consecutive access 
methods allow dual buffering except the consecutive up- 
date and consecutive update multivolume. If this operand 
is omitted or if SHR-Y is specified, one buffer is assumed. 



CHN-address specifies the address of the next DTF in the 
chain of DTFs. If there is no DTF chain or if this DTF is 
the last DTF in the chain, this operand should be omitted 
and X'FFFF' assumed. 



RCAD-address specifies the address of the leftmost byte of 
the logical record. If this operand is not entered, X'OOOO' 
is assumed. Depending on the disk access method being 
used for an input operation, either move mode or locate 
mode is used. If move mode is used, the record is provided 
at the address specified in the RCAD parameter. If locate 
mode is used, the address of the input record is contained 
at the displacement of $DFLRA in the DTF. 



The specified address plus the total length of the area 
must be less than logical X'EOOO' for files that are being 
shared or for files that are being used for external buffers 
(5704-SC2only). 



ENT-number specifies the number of entries in the master 
track index. This operand is specified only for indexed 
random or indexed add access methods. 



MVF-N/Y specifies whether the access method is multi- 
volume. If this operand is omitted, N (no) is assumed. 

LIM-N/Y is specified only for indexed sequential get and 
indexed sequential update. It specifies whether the sequen- 
tial access is within limits. If this operand is not entered, 
N (no) is assumed. 



MVFN-number indicates the number of volumes for a 
multivolume direct access method. This operand must be 
specified for these access methods. 



KEYL-number specifies the length of the key field and 
must be used for all indexed access methods, but no others. 
The key field length can be no more than 29 bytes. 



ORD-N/Y specifies whether an ordered load is to be used 
with the indexed output access method. This operand can 
be specified only with the indexed output access method. 
ORD-Y must be specified for indexed multivolume output 
access methods. If this operand is not entered, N (no) is 
assumed. 



KEYD-number is entered for all indexed access methods. 
It indicates the displacement into the record of the right- 
most byte of the key field. The displacement of the first 
byte in the record is zero, the second byte is one, and so on. 
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KEYA-address specifies one of the following and is a 
required operand for these access methods: 

• iViain storage address of the leftmost byte of the key 
field for indexed random access methods. 

• Main storage address of the leftmost byte of the relative 
record number field for direct access methods. 

• Main storage address of the leftmost byte of the save 
area for current and last keys for indexed sequential add 
access methods. 

• Main storage address of the leftmost byte of the save 
area for high and low keys for indexed sequential with 
limits access methods (LIM-Y). The specified address 
plus the total length of the area must be less than logical 
X'EOOO' for files that are being shared or for files that are 
being used for external buffers (5704-SC2 only). 
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MSTX-address specifies the address of the leftmost byte of 
the master track index in mai.n storage. This operand must 
be specified for indexed random and indexed add access 
methods. You must allocate space in main storage for the 
master track index. The length of the master track index is 
determined by the following formulas; 

• For single volume random access methods, 
Length = ENT (key length + 2) 

• For multivolume random access methods. 
Length '^ ENT (keylength + 2) 

ENT must be equal to or greater than 4. 



The specified address plus the total length of the area 
must be less than logical X'EOOO' for files that are being 
shared or for files that are being used for external buffers 
(5704-SC2 only). 



You must allocate the main storage space for the fields. 
The amount of space required is; 

• The number of bytes in the key field for indexed ran- 
dom access methods. 

• 23 bytes for direct access methods with decimal keys. 
The decimal key is located in the rightmost 15 bytes of 
the field. 

• 8 bytes for direct access methods with binary keys. 
The binary key is located in the rightmost 3 bytes of 
the field. 

• Two times the key length for indexed sequential add or 
indexed sequential with limits access methods. The low 
key is located in the left half of the field; the high key in 
the right half. 



MVFT-address must be specified for all multivolume direct 
files, and only for the access methods used with these files. 
This operand specifies the address of the leftmost byte of 
the table of extents used for the access methods used with 
these files. You must allocate main storage space for the 
table. The number of bytes allocated must be equal to 
seven times the number of volumes in the file. With 
5704-SC2, if the multivolume file is to be shared, the 
number of bytes allocated must be ten times the number 
of volumes in the file. The specified address plus the total 
length of the area mu.st be less than logical X'EOOO' for 
files that are being shared or for files that are being used 
for external buffers (5704-SC2 only). 



IBLKL-number specifies the number of sectors in the index 
buffer. This operand rs used only with indexed access 
methods. If this operand is not specified, one sector is 
assumed. For indexed sequential access methods with both 
input and add, the specified index buffer size applies to 
both the input index buffer and the add index buffer. For 
indexed random access methods, the specified buffer size 
applies only to the add index buffer. Increasing the size of 
this index buffer will increase the efficiency of processing 
for a random file. 



ADKEY-address specifies the address of the leftmost byte 
of an area used to save the highest key m the prime index 
and the highest key in the add index. The area at this ad- 
dress must be equal in length to 2 times KEYi for each vol- 
ume used by the file. This operand is reouired tor ir.uexed 
add, indexed random input and add, and indexed i .dRdom 
input, update, and add access methods. !t is iqnf)red it 
specified with other access methods. The specified address 
plus the total length of the area must be less than logical 
X'EOOO' for files that are being shared or for files that are 
being used for external buffers (5704-SC2 only). 



EOVK-address specifies the address of the leftmost byte of 
an area used to save a key if force end-of-volijme is spec- 
ified (by the HI KEY parameter on the FILE OCL sty;e 
ment) for a multivolume indexed output file The area at 
thTs address must be equal in length to KEYL. This oper 
and is used only when the multrvolurne mdext-d output 
access method is used and force end-of voiume will be usetJ. 
The specified address plus the total length of the area 
must be less than logical X'EOOO' for files th.U are being 
shared or for files that are being used for ext(irndl buffers 
(5704-SC2onlyl. 



Macro Instruct-on S:arprTirrnts 
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SHR-Y/N, applicable to Program Number 5704-SC2 only, 
allows the user to specify whether or not file sharing is 
permitted on the file. File sharing is permitted, when 
possible, if this parameter is not used. 



EXTBUF-Y/N, applicable to Program Number 5704-SC2 
only, allows the user to have external buffers. If this para- 
meter is not used, external buffering does not occur. 



Construct a Disk Get Interface ($GETD) 

The $GETD macro instruction generates the interface need- 
ed to communicate with disk data management when a 
record is being read from a disk file. To use this macro 
instruction, construct a disk DTF for the file and use the 
$DTFO macro instruction to establish the offsets for the 
DTF. You must also provide the labels for the necessary 
data management routines through EXTRN statements in 
your programs. The names of the data management mod- 
ules and the functions of the modules are shown in Figure 
11. If you will need to use the data in register 2 at a later 
time, you should save the contents of that register before 
issuing the $GETD macro instruction. 

The code generated by this macro instruction gives con- 
trol to the data management routine; the routine completes 
execution and returns control to the generated code The 
generated code tests the completion codes returned by data 
management. 



[Name] 


$GETD 


UAC-codel \ 
l[EBAC-code]( 

[,DTF-address] l.ERR-addressl 
[,EOF-address| (,NFR-address) 
[,LSTV-addressl [,NOKY-address) 



AC-code or EBAC-code specifies the appropriate access 
method for the file. The EBAC-code is for external buf- 
fering and is valid only for Program Number 5704-SC2. 
One of these parameters must be specified. 



The codes that must be used for the AC-code and the 
EBAC-code parameters are shown in Figure 1 1. 
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DTF-address indicates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 



ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code. 



EOF-address specifies the address in your program that 
receives control when the end-of-file is detected. If this 
operand is not supplied, no code is generated to check for 
the end-of-file condition. You must not use this operand 
with random or direct access methods. 

Note: If ERR or EOF addresses are not specified, you 
should check the return code in your program to determine 
the outcome of the operation. 



NRF-address must be used only for random and direct 
access methods. It specifies the address in your program 
that is to receive control when a no-record-found condition 
occurs. 



NOKY-address supplies the address in your program that is 
to receive control under either of the following conditions: 

• The requested key is too low for the current volume 
when processing an indexed random offline multivolume 
file. 

• The requested key is too high for any volume when 
processing an indexed random online multivolume file. 

This operand is not used with other access methods. 



Construct a Disk Put Interface ($PUTD) 

The SPUTD macro instruction generates the interface need- 
ed to communicate with disk data management when put- 
ting a record to disk or updating a previously retrieved 
record. You must provide a DTF for the file and use the 
$DTFO macro instruction to establish the offsets in the 
DTF. You must also provide, through EXTRN statements 
in your program, the labels of the disk data management 
modules necessary to perform the output operation (see 
Figure 11). If you will need to use the data in register 2 at 
a later time, you should save the contents of that register 
before issuing the $PUTD macro instruction. 



LSTV -address is used when processing a random, offline, 
multivolume file. This operand supplies the address in your 
program which receives control when the requested key is 
too high for the final volume in a multivolume file. 



Macro Instruction Statements 
Disk Device Support 
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Figure 1 1 (Part 1 of 2). Disk Data Management Modules Without External Buffering 
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I Figure 11 (Part 2 of 2). Disk Data Management Modules With External Buffering (5704-SC2 only) 
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The code generated by this macro instruction gives control 
to the data management routine; the routine completes 
execution and returns control to the generated code. Com- 
pletion codes are tested and control is returned to your 
program. 

The format of the $PUTD macro instruction is: 



[Name] 


$PUTD 


UAC-code] ( 
)[EBAC-code]i 










[,DTF-address] [,ERR-address] 






[,EOX-address] [,DUP-address] 






[,SERR-address] [,KERR-address] 






[.UPD-Y/Nl [,LSTV-address] 






[,NOKY-address] [,HKER-address) 



AC-code or EBAC-code specifies the appropriate access 
method for the file. The EBAC-code is for external buf- 
fering and is valid only for Program Number 5704SC2. 
One of these parameters must be specified. 

The codes that must be used for the AC-code and the 
EBAC-code parameters are shown in Figure 1 1. 



DTF-address specifies the address of the DTF associated 
with this file. If this operand is not specified, the address 
is assumed to be in register 2. 



ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code. 



EOX-address supplies the address in your program that is to 
receive control when an end of extent is reached during the 
operation. This operand is entered only when creating a 
consecutive or indexed file or when records are to be added 
to the file. 



DUP-address provides the address in your program that is to 
receive control when an attempt to add a duplicate record 
has occurred. This operand is used only with an add access 
method. 
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SERR-address is the address in your program where control 
is passed in the event of a sequence error while loading an 
indexed file. 



KERR-address specifies the address of your routine to be 
called when an attempt has been made to update a record 
in an indexed file and the attempt would destroy the 
record key. 



UPD-Y/N indicates whether an update is to be performed. 
If this operand is not entered, N (no) is assumed. 
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DISK-5444/5445/3340 specifies whether the disk device 
being used is the 5444 Disk Storage Drive Model 1, 5445 
Disk Storage, or the 3340 Direct Access Storage Facility. If 
a device is not specified, 5444 Disk Storage Drive Model 1 
is assumed. 



CYCL-number indicates the beginning cylinder to be 
accessed. You can specify the cylinder by a decimal num- 
ber (0-199) or a hexadecimal number (X'00'-X'C7'). If this 
operand is not entered, X'FF' is assumed. You must then 
insert the correct number into the lOB before performing 
the input/output operation. This can be done through the 
macro used to initiate the I/O operation. 



LSTV-address specifies the address in your program that 
receives control when a requested key is too high for the 
last specified volume. This operand is used only when 
processing an indexed, random, offline, multivolume file. 



NOKY-address supplies the address in your program that is 
to receive control under either of the following conditions: 

• The requested key is too low for the current volume 
when processing an indexed, random, offline, multi- 
volume file. 

• The requested key is too high for any volume when 
processing an indexed random online multivolume file. 

This operand is not used with other access methods. 



HKER-ad dress specifies the address in your program that is 
to receive control when an indexed sequential add multi- 
volume is attempted and the requested key is higher than 
any key presently in the file, but lower than the highest 
permissible key. 



Input/Output Block for Disk ($IOBDj 

This macro instruction generates a disk input/output block 
(JOB) for use by the disk input/output supervisor. A 30- 
byte lOB is generated for 5444, 5445, and 3340 disk 
devices. For a detailed description of the disk lOB, see 
Appendix C: Disk Input/Output Block. 

The format of the $IOBD macro instruction is: 



[Name] 


$IOBD 


[DISK-5444/5445/33401 [,CYL-numberl 

[,SCTR-number] [,HEAD-number J 
[,NUM-number) [.BUFF-address] 
[,Q-nunnber) [,ERREC-I0S/USER1 
l,LOG-Y/Nj [,VER-Y/N] [.CHN-addressl 



SCTR-number specifies the first sector to be accessed. The 
number specified must be a decimal from 1 through 48 for 
the 5444 disk drive, from 1 through 20 for the 5445 disk 
storage, or from 1 to 48 for the 3340 disk drive. If this 
operand is not entered, X'FF' is assumed. You must then 
insert the correct number before performing the input/ 
output operation. You can specify the sector through the 
$RDD and SWRTD macro instructions. 

HEAD-number is specified only for the 5445 or 3340 disk 
storage drives. It specifies the head to be used with the 
cylinder and sector when an I/O operation is performed. 
The number specified may be decimal (0-19) or hexa- 
decimal (X'00'-X'13'). If this operand is omitted, X'FF' 
is assumed and the value must be updated when the I/O 
operation is performed. 



NUM-number specifies the number of sectors used. You 
may specify the number in either decimal or hexadecimal 
form. If this operand is not entered, one sector is assumed. 



BUFF-address is the address of the leftmost byte of your 
data area. If this operand is omitted, X'FFFF' is assumed, 
and you must update the lOB before performing the input/ 
output operation. 

Q-number specifies the drive on which the record is located. 
'You may specify the disk drive alone F1, R1, F2, R2, D1, 
D2, D3/D31, D32, D33, D34, D4/D41, D42, D43, and D44, 
or you may specify the hexadecimal Q-code in the form 
Q-X'nn', where nn is a valid hexadecimal Q-code. The 
valid Q-codes are shown in Figure 12. If you specify 
only the disk drive, you must set the rear' 'write bits (the 
last four bits of the Q-code) before you can perform 
the I/O operation. This can be done through the SRDD 
or $WRTD macro instructions. 

Note: D31, D32, D33, D34, D41, D42, D43, and D44 
are for 5704-SC2 only. 
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I/O 
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Drive 3 


Drive 4 
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Control 
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Read 
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5444 Fixed Disk 




Control 


A8 


B8 


— 





Read 
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CO 
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Figure 12. Q-Byte Hexadecimal Settings' 

ERREC-IOS/USER indicates whether the input/output 
supervisor is to handle error recovery. If you specify lOS, 
the supervisor handles error recovery and retries the opera- 
tion when errors occur. If you specify USER, the supervisor 
does not retry the operation and returns control to you. If 
this operand is not specified, IDS is assumed. 



LOG-Y/N indicates whether the I/O supervisor is to log 
errors that occur during the operation. If you specify Y 
(yes), error conditions are logged on the system pack. This 
information is used by IBM customer engineers. N (no) 
indicates no logging is to be done for this lOB. If this oper- 
and is not entered, Y is assumed. 



Input/Output Block Offsets ($IOED) 

This macro instruction generates equates to establish labels 
for the disk lOBs. These labels are offsets from the begin- 
ning of the lOB and are used as displacements from the be- 
ginning of the 108 when you wish to refer to one of the 
fields. The labels generated by this macro instruction are 
given with the fields of the 108 in Appendix C: Disk 
Input/Output Block. To avoid duplicate labels, you should 
use this macro instruction only once in a program. 

The format of the $IOED macro instruction is: 





SIOED 





Read from Disk ($RDDj 

This macro instruction generates an interface to the disk 
input/output supervisor that is to read from the disk device. 
When using this macro instruction, you must: 

• Provide an 108 and use the SlOED macro instruction 
to establish the offsets in the 108. 

• Wait for the completion of the input operation (using 
$WAIT). 

• Check for end of extent when the record is received - 
completion code of X'70' (SCPEOX) at $DFCMP in the 
DTP. 

if both reading and writing for a program are to be per- 
formed using a single 108, the bits of the Q-byte are altered 
to indicate an invalid operation. In this case, you must set 
off the bits of the Q-byte for all but the first read (or write) 
operation in the program. 



VER-Y/N is used for output operations. Y (yes) indicates 
the written data should be verified; N (no) indicates it 
should not. If this operand is omitted, Y is assumed. 



CHN-address specifies the address of the leftmost byte of 
the next 108 for the operation if more than one 108 is 
required. 



If you will need to use the data in register 1 at a later time, 
you should save the contents of that register before issuing 
tiie SRDD macro instruction. 

The format of the SRDD macro instruction is: 



Name] 



SRDD 



IOB-address,CS-address,NSECT-number 
(,DISK-5444/5445/3340] 



Figure 12 applies on// to 5704-SC1. For 5704-SC2, you can 
specify only the disk drive (F1, RI.etc.) with the Q parameter, 
and read/write bits are set with $RDD or SWRTD. 
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lOB-address provides the address of the leftmost byte of 
the lOB which you created through your $IOBD macro 
instruction. The label provided must be the same as the 
name specified on your $IOBD macro instruction. 
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lOB-address provides the address of the disk I OB for this 
operation. The address is the name specified o,i the related 
$IOBD macro instruction. 



CS-address is the address of the rightmost byte of the main 
storage area containing the disk cylinder/sector address of 
the area you want to read. The cylinder/sector address for 
use with the 5444 is a two-byte, hexadecimal number. The 
first byte specifies the cylinder; the second specifies the 
sector. For use with the 5445, or 3340, a three-byte hexa- 
decimal disk address is provided through this entry. The 
first byte specifies the cylinder; the second, the head 
number; the third, the sector. 



NSECT-number indicates the hexadecimal number of sectors, 
minus one, to be read in this operation. 



DISK-5444/5445/3340 specifies whether the operation is 
on a 5444, a 5445, or a 3340 disk drive. If this operand is 
omitted, 5444 is assumed. 



Write to Disk ($WR TD) 

This macro instruction generates an interface to the disk 
input/output supervisor needed to write records to disk. 
When you use this macro instruction, you must: 

• Provide an lOB, and use the $IOED macro instruction to 
establish the offsets in the lOB. 

• Wait for the completion of the output operation (using 
$WAIT). 

If both reading and writing for a program are to be 
performed using a single lOB, the bits of the Q-byte are 
altered to indicate an invalid operation. In this case, you 
must set off the bits of the Q-byte for all but the first read 
(or write) operation in the program. 

If you will need to use the data in register 1 at a later time, 
you should save the contents of that register before issuing 
the macro instruction. 

The format of the SWRTD macro instruction is: 



CS-address is the address of the rightmost byte of the main 
storage area containing the disk cylinder/sector address of 
the area to which you want to write. The cylinder/sector 
address for use with the 5444 is a two-byte hexadecimal 
number. The first byte specifies the cylinder; the second 
specifies the sector. For use with the 5445 or the 3340, 
a three-byte hexadecimal disk address is provided through 
this entry. The first byte specifies the cylinder; the second, 
the head number; the third, the sector. 

I NSECT-number specifies the hexadecimal number of disk 
sectors, minus one, to be written. 

DISK-5444/5445/3340 specifies whether the operation is 
on a 5444, a 5445, or a 3340 disk drive. If this operand is 
omitted, 5444 is assumed. 



Wait for Disf: I OS Completion ($WAIT) 

This macro instruction is used with the $RDD and $WRTD 
macro instructions. It generates the code that allows you 
to wait foi completion of the disk lOS operation. You pro- 
vide the label of the associated lOB and an address to receive 
control in the event of an error. 

If you will need to use the data in register 1 at a later time, 
you should save the contents of that register before issuing 
the SWAIT macro instruction. 

The format of the SWAIT macro instruction is: 



[Name] 


SWAIT 


IIOB-label] | ,ERR-addressl 



[Name] 


SWRTD 


IOB-address,CS-address, NSECT-number 
[,DISK-5444/5445/3340] 



lOB-label is the name assigned to the JOB in the $IOBD 
macro instruction. This same lOB must have previously 
been specified in either a SRDD or $WRTD macro instruc- 
tion. If this operand is not entered, the address is assumed 
to be in register 1 . 



ERR-address specifies the address of the routine in your 
program that handles errors detected in the operation. If 
this operand is not entered, no error checking is performed, 
and you should check the return code in your program to 
determine the outcome of the operation. 
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3741 Device Support 

This section describes the macro instructions that support 
the directly attached 3741 Data Station IViodel 1 or 2 or 
Programmable Work Station Model 3 or 4. The following 
functions are provided: 

• Build a pre-open DTF and assign its offsets. 



BUFNO-1/2 allows you to specify either one or two buf- 
fers. If this operand is omitted, one buffer is assumed. 



CHN-address indicates the address of the next DTF in the 
chain of DTFs. If there is no DTF chain, the operand is 
omitted and X'FFFF' is assumed. 



• Build the interface required to read input records from 
the 3741 device via a GET. 

• Build the interface required to write output records to 
the 3741 device via a PUT. 

The DTFs provide information to the data management 
routines that perform the input/output operations. The 
interfaces to these operations are provided through the 
3741 macro instructions. 



UP-mask specifies the mask to test the eight external 
indicators. The code for the UP-mask must be specified 
as 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would enter UP-10010101. The UP-mask is compared 
to the external indicators set on by the SWITCH statement 
for conditionally opening files. If the bits that are on in the 
UP-mask are also on in the external indicators set on by the 
SWITCH statement, the file will be opened. If the UP-mask 
is all zeroes or not used, the file will be unconditionally 
opened. 



Define the File for 3741 ($DTFKj 

The DTF provides information needed to allocate, open, 
and access a file on the 3741 . This macro generates the 
DTF for this purpose. 

The format of the SDTFK macro instruction is: 



[Name] 



$DTFK 



l\IAME-filename,RECL-number,IO-address 
[,AC-J./0] l,RCAD-address] [,BUFNOJ_/2] 
[,CHN-address] [, UP-mask] 



NAME -filename specifies the name of the file. The name 
must be eight characters or less in length. This operand 
must be specified. 



RECL-number specifies the decimal length (from 1 to 128) 
of the logical record. This operand must be specified. 



lO-address provides the address of the leftmost byte of an 
area in main storage that contains the buffers and the lOB. 
This operand must be specified. The amount of storage 
must be the record length plus 26 times the BUFNO. 



Note: Information on setting external indicators (SWITCH 
statement) can be found in the IBM System/3 Model 15 
System Control Programming Reference Manual (for 
Program Number 5704-SC1 ), GC21 -5077, and IBM 
System/3 Model 15 System Control Programming Concepts 
and Reference Manual (for Program Number 5704-SC2), 
GC21-5162. 



Construct 3741 Get Interface (SGETK) 

The $GETK macro instruction generates the interface need- 
ed to communicate with the 3741 data management when a 
record is being read from the 3741. To use this macro 
instruction, construct a 3741 DTF for the file and use the 
$DTFO macro instruction to establish the offsets for the 
DTF. You must also provide an EXTRN statement with 
the label $$CPIP to use this macro. If you will need to 
use the data in register 2 at a later time, you should save 
the contents of that register before issuing the SGETK 
macro instruction. 

The code generated by this macro instruction gives control 
to the data management routine. The data management 
routine completes execution and returns control to the 
generated code. 



AC-l/0 specifies whether the DTF is input or output. If 
this operand is not specified, input is assumed. 



RCAD-address specifies the address of the leftmost byte 
of the logical record. If this operand is not entered, 
X'FFFF' is assumed. 



48 



The format of the $GETK macro instruction is: 



[Name] 



$GETK 



EOF-address [,DTF-address] [,ERR-address] 



EOF-address specifies the address in your program that 
receives control when the end of file Is detected. This 
operand must be specified. 



DTF-address indicates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 



Tape Device Support 

This section describes the macro instructions that support 
the IBM 3410/3411 Magnetic Tape Subsystem. The follow- 
ing functions are provided: 

• Build a pre-open DTF for tape and assign its offsets. 

• Build the interfaces required to read input records from 
a tape device via a get or a read. 

• Build the interfaces required to write output records to 
a tape device via a put or a write. 



ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is 
omitted, no code is generated to check for the controlled 
cancel completion code. 



Construct 3741 Put Interface ($PUTK) 

The $PUTK macro instruction generates the interface needed 
to put a record on the 3741 . You must provide a DTF for 
the file and use the $DTFO macro instruction to establish 
the offsets in the DTF. You must also provide an EXTRN 
statement in your program with the label $$CPOP to use 
this macro. If you will need to use the data in register 2 
at a later time, you should save the contents of that register 
before issuing the $PUTK macro instruction. 

The code generated by this macro instruction gives control 
to the data management routine. The data management 
routine completes execution and returns control to the 
generated code. 

The format of the $PUTK macro instruction is: 



[Name] 



$PUTK [DTF-address] [, ERR-address] 



DTF-address indicates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 



ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is 
omitted, no code is generated to check for the controlled 
cancel completion code. 



• Build the interface required to issue tape control 
commands. 

• Wait for completion of read, write, or tape control 
operations. 

The tape DTFs provide information to the tape data man- 
agement routines that perform the input/output operations. 
These operations are provided through the tape support 
macro instructions. 



Define the File for Tape ($DTFT) 

The DTF provides information needed to allocate and open 
a tape device. This macro instruction generates the code 
that builds the tape DTF. See Appendix B: Define the 
File Control Blocks for a description of the pre-open and 
post-open DTFs. 

The format of the $DTFT macro instruction is: 



[Name] 


$DTFT 


N AM E-filename,IO-address,BLKL-n umber, 
RECL-number [,UP-mask] [,AC-IN/OUT] 
[,CHN-address] [,BASIC-Y/N] 
[,RCAD-address] [, MODE-LOCATE/MOVE] 
[,MBUFF-Y/N_] [,RECFM-code] 
[,LIOA-number] [,SPAI\I-Y/N] [,CODE-A/E] 
[,OSET-B/number] [.END-code] [,MVF-Y/N] 



NAME-filename is a required operand specifying the name 
of the tape file. The filename can be up to eight characters 
in length and must be the same as the name of the // FILE 
statement. 
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lO-address specifies the address of the leftmost byte of the 
main storage area used to contain all buffers and lOBs. This 
operand is required. The length of the area specified by 
this address is specified in the LIOA operand. 



Note: If basic data management routines are used to 
process the file, this operand should point to a 40-byte area 
to contain the tape JOB. 



BLKL-number is a required operand that specifies the deci- 
mal block length for the file. The minimum block length 
allowed is 18 bytes, if a shorter length is specified, 18 is 
assumed. For files with fixed-length records, the block 
length must be a multiple of the record length; for files with 
variable-length records, the block length must equal the 
length of the longest record plus eight. 

Note: If basic tape data management is used, the block 
length in the DTF ($DFBKL) must be updated after the file 
is opened and before any read or write operation is per- 
formed. The field must also be updated before any subse- 
quent read or write if the length used is different than the 
previous read or write. 



/\C-//V/OL/r specifies the type of file. IN specifies an input 
file; OUT, an output file. If this operand is not entered, IN 
(input) is assumed. 

Note: The operation code in the Tape DTF will be initial- 
ized according to the entries specified (or defaults) of the 
AC and BASIC operands, as follows: 





AC-IN 


AC-OUT 


BASIC-Y 


Read forward 


Write 


BASIC-N 


Get 


Put 



CHN-address specifies the address of the next DTF in the 
chain of DTFs. If there is no DTF chain or if this DTF is 
the last DTF in the chain, this operand should be omitted 
and X'FFFF' assumed. 



RECL-number is a decimal value specifying the length of a 
logical record in the file. If variable-length records are used 
for the file, the record length specified must be equal to the 
longest record plus four. The minimum record length when 
variable-length records are used is four, which results in 
zero-length records. The minimum record length for files 
using fixed-length records is 18. This operand is required. 



UP-mask specifies the mask to test the eight external 
indicators. The code for the UP-mask must be specified 
as 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would enter UP-10010101, The UP-mask is compared 
to the external indicators set on by the SWITCH statement 
for conditionally opening files. If the bits that are on in 
the UP-mask are also on in the external indicators set on by 
the SWITCH statement, the file will be opened. If the 
UP-mask is all zeroes or not used, the file will be uncondi- 
tionally opened. 

Note: Information on setting external indicators (SWITCH 
statement) can be found in the IBM System/3 Model 15 
System Control Programming Reference Manual for Pro- 
gram Number 5704-SC1 , GC2 1-5077, and IBM 
System/3 Model 15 System Control Programming Con- 
cepts and Reference Manual for Program Number 5704- 
SC2,GC21-5162. 
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BASIC'Y/N specifies whether this DTF uses the basic access 
method. If tins operand is not entered, N (no) is assumed. 

Notes- 

1. BASIC-Y must be specified if any of the following macro 
instructions are used to process the file: $RDT, $WRTT, 
$CTLT or $W"n . 

2. If you process ASCII files using the basic access method, 
you must translate the characters in your program. 

3. Multivolume files are supported with the basic access 
method, but the EXTRN statement that is provided 
must be $$BTMIVI for multivolume support. $$BTAM 
and $$BTMIVI should not be u:,ed in the same program. 
$$BTIVIIVI supports both single and multivolume files. 

4. Deferred open is not allowed with the basic access 
method. 

RCAD-address specifies the symbolic record area address. 
This operand is required for all operations using the basic 
access method. If standard data management is used, this 
operand is required for an output operation and for an 
input operation using move mode. 



MBUFF-Y/N indicates whether more than orii' buff(;i is 
used. If this operand is not specified, N (no) is assumed. 
The number of buffers is determined by tin; Length of the 
I/O area, specified by the LIOA operand. ! ins operand 
should not be used if BASIC-Y is specified. 



LIOA-number is the total decimal length of tfie I/O area if 
more than two buffers are required (MBUFF Y), If the 
number specified is zero or if tfiis entry is oinitied, tvv/o 
buffers are allocated in the I/O area, if this entiy is not 
zero, as many buffers as possible are allocated in the I/O 
area. 

The following formula can be used to deterniiiu; tlie length 
of the I/O area: 

Length of the I/O area == (40 f block lenqtli) times 

(number of buffers) 

This operand should not be used if BASIC-Y is specified. 



MODE-LOCATE/MOVE indicates whether the locate mode 
or move mode is used. If this operand is not .specified, 
MOVE is assumed. When locate mode is specified, the record 
address (RCAD-address) is set to the address of the record 
in the buffer. When move mode is used, records are moved 
from the buffer to the location specified by the record 
address. 

Locate mode is valid only for input files. I hi-; operand 
should not be used if BASIC Y is specified 



RECFM-code specifies the record for mat used \(» ihc file. 
Thn codes and their meanings are: 

Code Record Format 

F Fixed, EBCDIC or ASCI! 

FB Fixed blocked, EBCDIC or ASCII 

V Variable, EBCDIC 

VB Variable blocked, EBCDIC 

D Variable, ASCII 

DB Variable blocked, ASCII 

If this operand is not specified. F is assumed. 



SPAN-Y/N specifies whether spanned records are used. If 
spanned records are used, BASIC-Y must also lie s|)ecified. 
If this operand is omitted, N (no) is assumei.l. Siiecifying 
SPAN-Y causes the spanned record bit in llie rape latjcl to 
be set on. When you use SPAN-Y, you mu:sr siian ihe rec- 
ords from block to block. 



CODE-A/E specifies whether the lile is an FBCiilt; file or 
ASCII file. If the file is an EBCDIC file,specity CODE E, 
If the file is an ASCII file or can he eithei ASCII or EBCDIC, 
specify CODE-A. If this operand is nor ciiterfMl, F is 
assumed. 



OSET-B/nun)ber specWte.s the buffer oifsei ol m /\SCII 
block. B indicates that the first four bytes of tfic iilock con 
tain the decimal block length and no buftei ollsj ; is i.nes 
em. B is valid only when RECFIVI D or REC:i M DB is also 
specified. Only OSET-8 or OSE'I-0(1 aie v'alid for output 
files. OSFT number st<ocifies, in decimal, tlie length of the 
buffer offset for the ASCII block. This buffei offset is 
skipped over when the record is sui^phi^d to your piouram. 
The maximum valid specification is OSET 99 If this oper 
and is not specified, zero is assumed. 



Macro Inslruction Stiittwiients 51 



END-code specifies the tape control actions to be taken 
when the file is closed. The valid codes and their meanings 



are: 



Code Action 

REWIND Rewind the tape 

UNLOAD Rewind and unload the tape 

LEAVE No action taken 

If this operand is not entered, REWIND is assumed. 



MVF-Y/N specifies whether this file has multivolume tape 
output. If this operand is not specified, Y (yes) is assumed. 



Construct a Tape Get interface ($GETT) 

1 he $GETT macro instruction generates the interface 
required to communicate with tape data management when 
a record is being read from a tape file. To use this instruc- 
tion, you must construct a tape DTP for the file and use 
t >e $DTFO macro instruction to establish the offsets in the 
DTP. 

If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $GETT macro instruction. 

You must also provide the labels for the necessary data 
management routines through EXTRN statements in your 
program. The names and functions of the data management 
routines are shown in Pigure 13. 



Module 
Name 



$$CSIT 

$$CSOT 

$$CSIA 

$$CSOA 

$$CSTI 

$$CSTO 

$$CSAI 

$$CSAO 



Type of File Being Processed 



EBCDIC fixed input 
EBCDIC fixed output 
EBCDIC or ASCII fixed input 
EBCDIC or ASCII fixed output 
EBCDIC fixed or variable input 
EBCDIC fixed or variable output 
EBCDIC or ASCII fixed or variable input 
EBCDIC or ASCII fixed or variable output 



The code generated by this macro instruction gives control 
to the data management routine; the routine completes 
execution and returns control to the generated code. If the 
ERR or EOP operand is specified, the generated code tests 
the completion code returned by data management and 
branches to your routine. If reading variable length records, 
tape data management returns the length of the record at 
label SDFCRL in the DTP. 

The format of the $GETT macro instruction is: 



'Narriel 



$GETT 



MODULE-name[,DTF-addressl 
[,RCAD-addre5s] [,OPC-Y/Nl 
[,ERR-addressl (.EOF-address) 



MODULE-name is a required operand that specifies the 
module name of the tape data management subroutine. 
Following are the module names used and the types of files 
they will process: 

$$CSIT EBCDIC fixed input 

$$CSIA EBCDICor ASCII fixed input 

$$CSTI EBCDIC (fixed or variable) input 

$$CSAI EBCDICor ASCII (fixed or variable) input 

An EXTRN must be provided for the module name that is 
used. 



DTF-address indicates the address of the leftmost byte of 
the DTP for this file. If this operand is not specified, the 
address is assumed to be in register 2. 



RCAD-address specifies the address of the leftmost byte of 
the logical record area. If this operand is not entered, the 
address of the record area is assumed to be in the DTF at 
SDFLRA. 

OPC-Y/N specifies whether to generate the code to set the 
operation code. If this operand is not entered, N (no) is 
assumed, and the operation code is not modified. 



ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code. 



Figure 13. Tape Data Management Modules 
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EOF-address specifies the address in your program that 
receives control when the end-of-file is detected. If this 
operand is not supplied, no code is generated to check for 
the end of-file condition. 

Note: If ERR or EOF addresses are not specified, you 
should check the return code in your program to determine 
the outcome of the operation 



Construct 



a Tape Put Interface ($PUTTj 



This macro instruction generates the interface needed to 
communicate with tape data management when writing a 
record to tape. You must provide a DTP for the file and 
use the $DTFO macro instruction to establish the offsets 
in the DTP. You must also provide, through EXTRN 
statements in your program, the labels of the tape data 
management modules necessary to perform the output 
operation (see Figure 13). 

If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the SPUTT macro instruction. 

The code generated by this macro instruction gives control 
to the data management routine. The routine completes 
execution and returns control to the generated code. If 
the ERR operand is specified, the generated code checks 
the completion code for errors and branches to your error 
routine if errors occurred. 

The format of the $PUTT macro instruction is: 



Name] 



SPUTT 



MODULE-name [,DTF-address) 
I, RCAD -address] 1,0PC-Y/N] 
l.LENAD-address] l.ERR-addres 



MODULE-name, is a required operand, and specifies the 
name of the tape data management subroutine to be used. 
Following are the module names used and the type of. 
files they will process: 



$$CSOT 
$$CSOA 

SSCSTO 
$$CSAO 



EBCDIC fixed output 
EBCDIC or ASCII fixed output 
EBCDIC fixed or variable output 
EBCDIC or ASCII fixed or variable output 



DTF-address specifies the address of the leftmost byte of 
the DTP for the file. If this operand is not specified, the 
address is assumed to be in register 2. 



LENAD-address specifies the address of the rightmost byte 
of a two-byte area which contains the length of the current 
record. This operand is used only for variable files. If this 
operand is not specified, the length of the record is 
assumed to be in the DTP at $DFCRL. 



RCAD-address specifies the address of the leftmost byte of 
the record to be put. If this operand is not entered, the 
record address is assumed to be in the DTP at label $DPLRA. 



OPC-Y/N specifies whether to generate the code to set the 
operation code. If this operand is not entered, N (no) is 
assumed, and the operation code is not modified in the 
DTP. 



ERR-address specifies the address in your program where 
control should be passed if a permanent I/O error occurs. 
If this operand is not entered, no permanent I/O error 
checking code is generated and you should check the 
return code in your program to determine the outcome of 
the operation. 



Read from Tape ($RDT) 

This macro instruction generates an interface to basic tape 
data management to read from a tape device. When using 
this macro instruction, you must; 

• Provide a tape DTP and use $DTPO to establish the 
offsets in the DTP. 

• Wait for completion of the input operation and ch > k 
for end-of-file by using the $WTT macro instruction. 

• Provide EXTRIM statements in your program for the 
basic tape data management module ($$BTAM or 
$$BTMM) and for the entry point to the read routine 
in that module (DMBTRW). 

If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $RDT macro instruction. The generated code for this 
macro instruction uses register 2. 

The code generated by this macro instruction branches to 
basic tape data management to begin the read operation. 



Macro Instruction Statements 53 



The format of the $RDT macro instruction is; 



IM.iiTin] 


$K[vr 


1 DTF. address] [,RCAD-addressl 
I.DIHECT-FORW/BACKI 



DTf- address specifies the address of the leftmost byte of 
the DTF for the file. If this operand is not entered, the 
address is assumed to be in register 2. 



RCAD-adrlres.; specifies the address of the leftmost byte of 
the recoil I aiea. If this operand is not specified, the address 
is assumed tv) U; in the DTF at $DFLRA. 



Dl RtiCl i QHIV or BACK specifies the direction of the 
read and causes ihe operation code in the DTF to be set 
(see AC opeiaiul oi SDT FT]. If this operand is not 
entered, tlie operation code is unchanged. 



I/Vrite to liifii- i$WHTT) 

This iiiai;i.) is isii iiction genei ates the interface to basic tape 
data iiiaiia(ji.iiUMit rieeded to write records to tape. When 
you ' ihis nia(.n,i instruction, you must: 

• Provide a DTF for the file and use the $DTFO macro 
iMsti iK.iioh :., ostablish the offsets in the DTF, 

• Wait *i.f the completion of the I/O operation by using 
^' '•: iVV i i oiacto instruction. 

• '■ ' 'iiii; !. X i si^i statements in your program for the 
basic tai ... data management module (SSBTAM or 
?;.SB riViM) and fui the entry point to the write routine 
ih h,^^ module (DMBTRW), 

h vc'.i v'viii iu:f!d 10 use the data in register 2 at a later time, 
\:)v sii nild ,avi- the contents of that register before issuing 
tiie SWR 1 r iiiav.ro instruction, !)ecause the generated code 
foi thai 'iiaciii instiuci uses register 2. 

The code generated by this macro instruction branches to 
l,)asic ta|)i; ii.itJ management to start the operation. 



DTF-address is the address of the leftmost byte of the DIF 
for the file. If this operand is not specified, the address of 
the DTF is assumed to be in register 2. 



RCAD-address specifies the address of the leftmost byte of 
the record area. If this operand is not specified, the address 
is assumed to be in the DTF at $DFLRA, 



OPCY/N specifies whether the write operation code in the 
DTF is to be set. If N (no) is specified or if this operand is 
not entered, the operation code is not modified in the DTF, 



Control Command for Tape ($CTL T) 

This macro instruction generates the interface to basic 
tape data management to issue control commands to the 
tape device. It is not used to get records from or put 
records out on a tape file. To use this macro instruction, 
you must: 

• Provide a DTF for the file on the tape device and use 
the $D TFO macro instruction to establish the offsets in 
the DTF, 

• Wait for completion of the operation by issuing the 
$WTT macro instruction, 

• Provide EXTRN statements in your program foi the 
basic tape data management module ($$BTAI\/I or 
$$BTMIVi) and for the entry point to the control routine 
in that module (DMBTPS). 

If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the SCTLT macro instruction. 

The code generated by this macro instruction branches to 
the basic tape data management to initiate the operation. 



The format of the $CTLT macro instruction is; 



Name) 



SCTLT 



IDTFaddressl [,OPC-code] 



L"] 



The format of the $WRTT macro instruction is; 



I Name j! SWRTT 



I DTF-address) [, RCAD-address] 
l,OPC-Y/N] 
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DTF-address specifies the address of the leftmost byte of 
the DTF for the file on the tape device. If this operand is 
not specified, the address of the DTF is assumed to be in 
register 2. 



OPC-code specifies the control operation to be performed 
If this operand is not specified, no code is generated to 
modify the operation code in the DTF. The valid codes 
and their meanings are: 



The format of the $WTr m 



aero iiistruction is: 



Code 

FSF 

FSB 

BSF 

BSB 

REW 

RUN 

WTM 



Operation 

Forward space file 
Forward space block 
Backspace file 
Backspace block 
Rewind tape 
Rewind and unload tape 
Write tape mark 



Wait For Tape I/O Completion ($WTT) 

This macro instruction is used with the $RDT, SWRTT 
and $CTLT macro instructions. It generates the linkage to 
basic tape data management to wait for the completion of 
operations that have been initiated. You must provide the 
address of the tape DTF for the file and use the SDTFO 
macro instruction to establish the offsets for that DTF 
You must also provide EXTRN statements in your program 
tor the basic tape data management module ($$BTAM or 
$$BTMM) and for the entry point to the wait routine in 
that module (DMBTWT). You may also provide addresses 
where control is to be returned in the event of a permanent 
I/O error, end-of-file condition, or end-of-tape condition. 

if you will need to use the data in register 2 at a later time 
you should save the contents of that register before issuing 
the $WTT macro instruction. 

The generated code from this macro instruction checks the 
completion code in the DTF to determine the outcome of 
the operation. When an abnormal completion is detected 
control IS passed to the appropriate address in your program 
(If you have specified ERR, EOJ, or EOT) or to the next 
instruction in your program. 




DTF-dddress) [,ERR-address] 
,EOK addressi [,EOT-address] 
[,WLKS-addressJ uWLRL-addressJ 



DTF-address specifies the address of the leftmost byte in 
the DTF for the file. If this operand is omitted, the 
address of the DTF is assumed to be in register 2. 

ERR-address is the address of the routine in your program 
that receives control when a controlled cancel is indicated 
m the completion code. If this operand is not entered, the 
controlled cancel is ignored and control returns to the' 
next instruction in your program. 



EOF-address specifies the address of your routine that 
receives control when end-of-file occurs. If this operand is 
omitted, the end-of-file condition is ignored and control 
returns to the next instruction in your program. 

EOT-address is the address of the routine in your program 
that receives control when end-of-tape is detected. If this 
operand is not specified, the condition is ignored and con- 
trol returns to the next instruction in your program. 

WLRS-address specifies the address of the routine that is 
to get control when a record that is too short is read. This 
operand should be used when waiting for a completion of a 
read operation. 

WLRL-address specifies the address of the routine that 
should get control when a record that is too long is read. 
This operand should be used when waiting for the comple- 
tion of a read operation. 

Note: If ERR, EOF, EOT, WLRS, or WLRL addresses are 
not specified, you should check the return code in your 
program to determine the outcome of the operation. 
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Device Independent Support 

This section describes the macro instructions that support 
device independent files. Device independent data manage- 
ment supports sequential files on disk, tape, and card 
devices, and on printers. The device type is determined at 
execution time according to data on the file card. The fol- 
lowing functions are provided: 

• Build a pre-open DTF for device independent data 
management. 

• Build the interface required to get a fixed length record 
from a file. 



Note: The record length will be changed by the device- 
independent open to accommodate the physical device size. 
If the record length is greater than the physical device 
length, the record length is changed to the device length. 
For output files, this means that the number of positions 
by which the size of the logical record area exceeds the 
device size will be truncated from the rightmost positions 
of the logical record. For input files, this means that the 
contents of the positions by which the size of the logical 
record area exceeds the device size will not be changed. If 
the record length is less than the physical device length, the 
record length is not changed and, for output files, the 
physical record will be padded with blanks. 



• Build the interface required to put a fixed length record 
to a file. 

The device independent DTF provides information to the 
device independent data management routines that perform 
the input/output operation. 



lO-address specifies the address of the I/O area. This area 
must be on a 256-byte boundary for each buffer. This I/O 
area must be at least equal in length to block length plus 40 
bytes, or be 286 bytes, whichever is greater. This operand 
is required. 



Define the File for Device Independent ($DTFIj 



AC-IN/OUT spedf\es the type of file. IN specifies an input 
file; OUT, an output file. 



The $DTFI macro instruction provides information needed 
to allocate, open and access a device-independent file. This 
macro instruction generates the code that builds a device- 
independent DTF. See Appendix B: Define the File Con- 
trol Blocks for a description of the device-independent 
DTFs. To use this macro instruction, you must use the 
$DTFO macro instruction to establish the offsets for the 
DTF. 

The format of the $DTFI macro instruction is: 



INamel 


$DTFI 


NAME-fiiename, RECL-number, lO-address 
[, AC-IN/OUT] [,BLKL-numberl 
I.RCAD-address] [,BUFN0-1_/2! 
[,CHN-address] [,UP-mask) 



NAME-filename specifies the name of the file. The name 
can be eight characters or less in length. This operand must 
be specified. 



If this operand is omitted, IN (input) is assumed. 



BLKL-number specifies the decimal block length for the 
file. If this operand is not specified, the value of the record 
length (RECL) is assumed. 

Note: For tape files, the actual block length is used. For 
disk files, the block length is rounded down to a multiple of 
256. The block length is not used for unit record devices. 



RCAD-address specifies the address of the leftmost byte of 
the logical record. If this operand is not entered, X'FFFF' 
is assumed and the address must be supplied when an opera- 
tion is requested. 



BUFNO-1/2 specifies the number of buffers to be used. If 
this operand is not specified, 1 is assumed. 



RECL-number is a decimal value specifying the length of a 
logical record in the file. This operand is required. 



CHN-address specifies the address of the next DTF in the 
chain of DTFs. If there is no DTF chain or if this DTF is 
the last DTF in the chain, this operand should be omitted 
and the end of chain (X'FFFF') assumed. 
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UP mask specifies the mask to test the eight external 
indicators. The code for the UP-rnask must f)e specified 
rj.-, 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would enter UP 10010101. The UP-mask is com^ 
pared to the externa! indicators set on by the SWITCH 
statement foi conditionally opening files, if the bits that 
are on in the UP-mask arc also on in the external indicators 
sei on !>v the SWITCH statement, the file will be opened. 
!i the UP-mask is all zeroes or not used, the file will be 
unconditional I y opened. 

Note: Information on setting externa! indicators (SWITCH 
statement) can be found in the IBM System /3 Model 15 
System Control Programming Reference Manual (for 
Proq.am Number -5704-SC1!, GC21 5077, and in the 
IBM System /3 Model 1 5 System Control Programming 
Concept! and Hefe'ence Manual 



Construct a Device-Independent Get Interface ($GETIj 

i he SGETI macro instruction generates the interface need- 
ec! to communicate with device-independent data manage- 
ment when a record is being read. To use this macro 
instruction, you must construct a device-independent 
DTF for the file and use the $DTFO macro instruction to 
estab' --.ii tne offsets in the DTF. In addition, you must 
provide the labels for the necessary data management 
routines through an EXTRN to $$CSII in your programs. 

If you w.!i neecj to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the SGETI instruction. 
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EOF-address specifies the address in your program that 
receives control when the end-of-file is detected. If this 
operand is not supplied, no code is generated to check for 
the end-of-file condition. 

Note: If ERR or EOF addresses are not specified, you 
should check the return code in your program to deter- 
mine the outcome of the operation. 



Construct a Device-Independent Put Interface ($PUTIj 

The SPUTI macro instruction generates the interface need- 
ed to communicate with device-independent data manage- 
ment when writing a record. To use this macro instruction, 
you must construct a device-independent DTF for the 
file and use the $DTFO macro instruction to establish the 
offsets in the DTF. In addition, you must provide the 
labels for the necessary data management routines through 
an EXTRN to $$CSIO in your programs. 

If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the SPUTI instruction. 

The format of the $PUTI macro instruction is: 



[Name] 



SPUTI 



[DTF -address] |,RCAD-address] 
[,ERR-addressl (,EOX-address] 



DTF addressind'icates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 



The SormaT of the SGETI 



macro instruction is: 



[Name] 



SGETf 



[D I F-address] (,RCAD-addressl 
[,fRR-address] [.EOF-address] 



RC AD address specifies the address of the leftmost byte of 
the record area. If this operand is not entered, the address 
is assumed to be in the DTF at $DFLRA. 



O'fi^ audress iruiicates the address of the leftmost byte of 
the DTF f(ji this file. If this operand is not specified, the 
address i^ assumed to be in register 2. 



fiCAD-address specifies the address of the leftmost byte 
oi the record area, if this operand is not entered, the 
address is assumed (o be in the DTF at SDFLRA. 



ERR address supplies the afUJress in your program where 
control is passed ii ttie contrvjiied cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is yeneiated to check for the controlled cancel 
completion code. 



ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code and you should check the return code in 
your program to determine the outcome of the operation. 

EOX-address specifies the address of the routine that 
receives control when the end of extent on disk is reached. 
The file will not contain the record for which the put was 
requested. 

if this operand is not specified, the code that checks for 
the end of extent completion code is not generated. 



Macro Instruction Statements 
Device-Independent Support 
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CRT/Keyboard 

This section describes the macro instructions that support 
the CRT/Keyboard. This support can be grouped in two 
categories: display support and program function key sup- 
port. It provides the following capabilities: 



PUTLOC-number specifies a number which represents the 
starting location on the CRT for a put request. Valid 
entries for this operand are from through 278. If this 
operand is not specified, (the first CRT position) is 
assumed. If the number exceeds 278, no data is written. 



• Builds a pre-open fjTF for the CRT/Keyboard data 
management. 

• Builds tne interface to get a record from the CRT/ 
Keyboard. 

• Builds the interface to put a record to the CRT, 

• Builds the interface to first put a record to the CRT, and 
then to get a record from the Keyboard. 

• Builds the interface to use the program function keys. 

The CRT/Keyboard provides information to the CRT/ 
Keyboard data management routines that perform the 
input/output operations. 



Display Support 

The macros which follow support the display functions of 
the CRT/Keyboard. 



Define the File for CRT ($DTFSj 

The SDTFS macro instruction provides information need- 
ed to allocate, open, and access a CRT file. This macro 
instruction generates the code that builds a CRT DTF. 
When using this macro, $DTFO C/?r-/ or /1/./.-V must 
also be used. See Appendix B: Define the File Control 
Blocks for a description of the CRT DTFs. 

The format of the $DTFS macro instruction is: 



[Namel 


$DTFS 


IPUTDAT-addressI [.PUTLOC-number] 
l,UP-maski t.CHN-dddressi 
I.PUTLEN-number! i.OPC-code] 
I.GETDAT-addressj l.GETLOC-numberl 
[,GETLEN-numberJ i,BLANK-Y/N! 



PUTDATaddress specifies the leftmost byte of the logical 
record for a put request. For a $PGS request, this area is 
used for the output. If this operand is not specified, 
X'OOOO' is assumed, and the address must be updated with 
(or prior to) the first SPGS or $PUTS request issued. 



UP-mask specifies the mask to test the eight external 
indicators. The code for the UP-mask must be specified 
as 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would enter UP-10010101. The UP-mask is compared 
to the external indicators set on by the SWITCH statement 
for conditionally opening files. If the bits that are on in the 
UP-mask are also on in the external indicators set on by the 
SWITCH statement, the file will be opened. If the UP-mask 
is all zeroes or not used, the file will be unconditionally 
opened. 

Note: Information on setting external indicators (SWITCH 
statement) can be found in the IBM System /3 Model 15 
System Control Programming Reference Manual (for 
Program Number 5704-SC1), GC21-5077, and in the 
IBM System/3 Model 15 System Control Programming 
Concepts and Reference Manual (for Program Number 
5704-SC2) GC21-5162. 



CHN-name specifies the address of the next DTF in the 
forward DTF chain. If there is no DTF chain or if this DTF 
is the last one in the chain, this operand should be omitted 
and end of chain (X'FFFF') assumed. 



PUTLEN-number specifies the number of bytes to process 
for a put request. If this operand is not specified, the miss- 
ing information must be supplied with (or prior to) the first 
SPGS or SPUTS request. 

Valid entries for this operand are from 1 through 279. If 
this number plus the entry for the PUTLOC operand 
exceeds 279, the data written is truncated at location 278. 

OPC-code specifies the operation code to be set. If this 
operand is not specified, the information must be supplied 
with (or prior to issuing) the first $GETS, SPUTS, or SPGS 
request. The codes and their meanings are: 

Code Meaning 

IN Set operation code for input only (SGETS). 

INR Set operation code for input on request 

(SGETS). 
OUT Set operation code for output only 

(SPUTS). 
OUTIN Set operation code for output/input 

(for SPGS). 
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GETDAT-address specifies the leftmost byte of the area 
into which the input data will be placed for a get request; 
for a SPGS request, this area is used for the input. If this 
operand is not specified, X'OOOO' is assumed, and the infor- 
mation must be supplied with (or prior to issuing) the 
first $GETS or $PGS request. 



GETLOC-number specifies a number which indicates the 
starting location on the CRT for a get request. Valid 
entries for this operand are through 278. If this operand 
IS not specified, (the first CRT position) is assumed. If 
a number greater than 278 is specified, no data will be 
read. 



DTF-address specifies the leftmost byte of the DTF for 
this file. If this operand is not specified, the address of the 
DTF is assumed to be in register 2. 



GETDAT-address specifies the leftmost byte of the area 
into which the data will be placed. 

GETLEN-number specifies the number of bytes to get. 
Valid entries for this operand are 1 through 279. If the 
sum of this number plus the number specified for the 
GETLOC operand exceeds 279, the data read is truncated 
after location 279. 



GETLEN-number is a decimal number which represents the 
number of bytes to get. If this operand is not specified, 
X'OOOO' is assumed, and the missing information must be 
supplied with (or prior to issuing) the first $PGS or $PUTS 
request. Valid entries for this operand are 1 through 279. 
If this number plus the entry specified for the GETLOC 
operand exceeds 279, the data read is truncated after 
location 278. 



BLANK-Y/N determines whether to leave the previous data 
in the CRT buffer or to blank the buffer. If Y (yes) is 
specified, the operation code is set to blank the buffer. If 
this operand is not specified, N (no) is assumed. When 
used in conjunction with the $PUTS and $PGS macros, 
the operand causes all 279 bytes to be blanked; when used 
with $GETS, only the input area is blanked. 



Get a Record from the CRT/Keyboard ($GETS) 

The $GETS macro instruction generates the interface need- 
ed to communicate with CRT data management when a 
record is being read from the CRT. To use this macro in- 
struction, construct a CRT DTF for the file and use the 
$DTFO macro to establish the offsets for the DTF. You 
must include an EXTRN for $$CODM. If you will need 
to use the data in register 2 at a later time, you should 
save the contents of that register before using the SGETS 
macro instruction. 

The format for the SGETS macro instruction is: 




[DTF-address] [.GETDAT-address] 
[.GETLEN-number] [.GETLOC-number] 
[.BLANK-Y/N] (,OPC-IN/INR/N] 
[.EOF-address] 



GETLOC-number specifies a number representing the start- 
ing location on the CRT for this get. Valid entries for this 
operand are (the first CRT position) through 278. If this 
entry exceeds 278, no data is read. If this operand is omit- 
ted, the corresponding entry in the DTF is not modified. 



BLANK-Y/N determines whether to leave the previous data 
in the CRT buffer or to blank the buffer. If Y (yes) is 
specified, the operation code is set to blank the buffer. If 
this operand is not specified, N (no) is assumed. 

OPC-IN/INR/N determines whether to set the operation 
code to input only (IN), to input on request (INR),orto 
leave the operation code unchanged. If INR is entered, the 
operator is prompted WAITING FOR REQUEST. Then, 
when the PA1 key is pressed, ENTER DATA is prompted. 
If N (no) is specified or if this operand is omitted, the 
operation code is not changed. 

EOF-address specifies the address in your program that 
should receive control when end of file is recognized (end 
of file is indicated by /* as the first two characters of input) 
If this operand Is not specified, no code is generated to 
check for the end-of-file condition, and you should check 
the return code in your program to determine the outcome 
of the operation. 



Generate a PUT/GET Operation Through CR T Data 
Management ($PGS) 

This macro instruction generates a PUT/GET data request 
to CRT data management. To use this instruction, you 
must construct a CRT DTF for the file and use the SDTFO 
macro instruction to establish the offsets in the DTF. 
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Yf'i! mus;; alsr siiriyii.o the labels for the nt;C(issary data 
manayemeht .ontinos through an EXTRN for $$CODM. 

!f yoii jj)\\ iioui! iu use tisu data In register 2 at a later time 
you sh<j.J(J save the content', of that register before Issuing 
the $PGS macro Instrnctloii. 

Ihi; inriiijit fu! tiie $PGS macro Instruction Is: 



-noljsPGn 



lOrt dd()r:"ss| !,BLANK-Y/jMl I.OPC-Y/N] 
!,PU rDAT-afidiHssl |,PLITLEN-nuniber I 
f.PUTLOCruKTiberl I.GETDAT-addressl 
!,Gi-"l t--M-ia:mbei-] l,GETt.OC-numberl 
I FOE-riddtess! 



DTF iidrli-fss specifies the address of the DTP for this file. 
If the opeiand is not sfieclfied, the address Is assumed to 



^'/ ANK ''',N iielei rnine-s whether to blank the data in tlie 
:.?79 i)yi!; -npiit area befou; -j CF^T operation. If Y (yes) is 
-.in^c'i-i'd, die ■,>r)eration code is set to blank the input area; 
I :iiis '.ii)i;i jrii.i IS omittfid, N (no) is assumed and the area 
i; riijt biankf.d. 



GETLEN-nuinber specifies the number of liytes to get from 
the CRT. Valid entries for tiiis operand are 1 through 279. 
If the sum of this number plus the entry specified for the 
GETLOC operand exceeds 279, the data read is truncated 
after location 278. 



GETLOC-number specifies the starting location on the CRT 
for this get request. Valid entries for this operand are 
(the first CRT position) through 278. If this number 
exceeds 278, no data is read. 



EOF address specifies the address in your program that 
should receive control vvfien end of file is recognized 
(Indicated by the characters /* in the first tv>yo Input posi- 
tions). If this operand is not specified, no code Is generated 
to check for the end-of-fiie condition, and you should 
check the return code m your program for the outcome of 
the operation. 

Note: If the following operands - PUTDAT, PUTLOC, 
PUTLEN, GETDAT, GETLOC, GETLEN, BLANK, or OPC 
- are not specified, you must supply the missing informa- 
tion in the DTP before issuing the first $PGS request. 



OI'C- Y/N s}.'ec!fi.;s whether to set the operation code to 
■iit[)ur/M:pi.ii If M is specified or if this operand is not 
s|)ocifie.i, :M (i.o) li assumed, and the operation code Is not 
modified in the UTF. 



PUT DA T-address identifies the leftmost byte of the user 
area from whici'i the data will be taken. 



PUT [. EN-number specifies the number of bytes to put to 
the CRT. Valid entries for this operand are 1 through 279. 
if liie sum of tins number plus the entry specified for the 
PUTLOC o|3erand exceeds 279, the data written Is truncated 
after location 278. 

PUTLOC-number specifies the starting location on the 
screen for this put request. Valid entries for this operand 
are (the first CRT position) through 278. If this number 
exceeds 278, no data is written. 



GETDAT-number specifies the leftmost byte of the area 
into which the data will be placed. 



Put a Record to the CRT via Data Management ($PUTSj 

This macro instruction generates a put data request to CRT 
data management. To use this macro instruction, you must 
construct a CRT DTP for the file and use the $DTFO 
macro Instruction to establish the offsets in the DTP. 

If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $PUTS macro instruction. You must also provide the 
labels for the necessary data management routines through 
an EXTRN to $$CODM. 

The format for the $PUTS macro instruction is: 



[Name) 


$PUTS 


[DTF-addiessi r,BLANK-Y/JMJ |,0PC-Y/N_1 
l,PUTDAT-address| |, PUTLOC-number | 
[.PUTLEN-number] 



DTE address specifies the address of the DTP for this file. 
If this operand Is not specified, the address is assumed to be 
in register 2. 
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BLANK-Y/N specifies whether to blank the data in the 
279-byte input area before a CRT operation. If Y (yes) is 
specified, the operation code is set to blank the input area. 
If this operand is omitted or if N (no) is specified, the input 
area is not blanked. 



OPC-Y/N specifies whether the operation code is set to out- 
put only. If this operand is omitted, or if N (no) is specified, 
the operation code is not modified. 



Byte Field Description 

0-6 Reserved 

7 CQE Q-code 

8 CQE request code 

9 PF key requested 

The format of the SCQEP macro instruction is: 



iNamei SCQEP |KEY-number| 
I I 



PUTDAT-address specifies the leftmost byte of the area 
from which the data will be taken. 



PUTLOC-number specifies the starting location on the CRT 
for this put. Valid entries for this operand are (the first 
CRT position) through 278. If this numbei exceeds 278, 
no data is written. 



PUTLEN-number specifies how many bytes to put to the 
CRT. Valid entries for this operand are 1 through 279. If 
the sum of this number plus the entry specified for the 
PUTLOC operand exceeds 279, the data written is truncated 
at location 278. 

Note: If the following operands ~ PUTDAT, PUTLOC, 
PUTLEN, BLANK, or OPC - are missing, the missing in- 
formation must be supplied in the DTP before the first put 
request is issued. 



Program Function Key Support 

Program Function (PF) keys 1-9 on the CRT/Keyboard are 
available for use in your program. When an assigned PF key 
is pressed, the program requesting its use is notified. The 
program may then test to see which key was pressed in 
order to condition subsequent operations. 



Generate a Parameter List for a Program Function Key 
Request ($CQEPj 

This macro instruction generates a ten-byte parameter list 
which requests a program function key. The format of the 
generated list is as follows: 



KEY-number specifies the number of the program function 
key requested (keys 1-9 are available for assignrrsent to your 
program). If this operand is not specified, PF9 is assigned. 



Allocate Program Function Key to a Program ($PFKY! 

The $PFKY macro should be used initially to allocate a 
function key to a program for subsequent testing via the 
$PFKT macro. If the function key has already been 
allocated, the ERR branch will be affected. 



The format of the $PFKY macro instruction is: 



[Namel 



SPFKY ICQE-addressi [,EPR -addrf sO 



J 



CQE address specifies the address of the parameter list that 
specifies which program function key to assign, and loads 
this address into register 1 . If this operand is not specified, 
the address is assumed to be in register 1 (see $CQFP). If 
you will need the contents of register 1 at a later time, you 
should save the contents of that register before issuing the 
SPFKY macro instruction. 



ERR-address specifies the address in your prograrri that 
should receive control if the completion code in the param 
eter list indicates that the requested key is not available 
If this operand is not specified, no code is generated to 
check for a successful key assignment, and you should 
check the completion code in your parameter list to deter- 
mine the outcome of the operation (a value of X'40' at 
displacement 2 in the parameter list indicates that a key 
was successfully assigned). 



Macro Instiui: ;oi> :r.raier;t";its 
CRT/Keyboarn SupDDit 
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Test for Program Function Key Pressed ($PFKT) 

Your program can either wait for a program function key 
to be pressed, or it can test at any time to see if a specified 
key was pressed. Only one program function key can be 
pressed before your program is notified. 

This macro instruction generates code to test whether a 
program function key was pressed. The chart under Using 
More Than One Program Function Key shows the value to 
check for to determine if a specific key was pressed. 

The format of the $PFKT macro instruction is: 



[Name] 



$PFKT 



[CQE-address] [,WAIT-Y/N1 
[,LABEL-addressl 



CQE-address specifies the address of the parameter list that 
was used to request the assignment of the program function 
key being tested, and loads this address into register 1 (the 
address is assumed to be in register 1 if this operand is not 
specified). If you will need the contents of register 1 at a 
later time, you should save the contents of that register 
before issuing the SPFKT macro instruction. 



WAIT-Y/N specifies whether to wait for the assigned pro- 
gram function key to be pressed. If Y (yes) is specified, 
your program waits until an assigned key is pressed. If no 
keys have been assigned, this is a permanent wait. If N 
(no) is specified, or if this operand is omitted, the LABEL 
operand must be specified. 



LABEL-address specifies the address in your program that 
should receive control when an assigned program function 
key is pressed. This operand is used only if WAIT-N is 
specified or if the WAIT operand is omitted. 



Using More Than One Program Function Key 

If you want to use more than one program function key in 
your program, you must request each key separately, using 
the $PFKY rnacio instruction. You must use a different 
parameter list tor each different key you wish to assign. 
To test if a program tunction key was pressed, you should 
issue the SPFKT macro instruction. Then, when control 
is returned to your program, you should determine which 
key was pressed. The following chart shows which fields 
in the parameter list should be modified and investigated: 



Value to set a displacement 
OS before issuing SPFKY 
PF Key macro instruction 



2 
3 
4 
5 
6 
7 
8 
9 



X'OO- 
X'05' 
X'OA' 
X'OF' 
X'14' 
X'19' 
X'lE' 
X'23' 
X'28' 



Value to test for at dis- 
placement 02 after issuing 
SPFKY macro instruction 

X'31' 
X'32' 
X'33' 
X'34' 
X'35' 
X'36' 
X'37' 
X'38' 
X'39' 
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Chapters: OCL and Sample Program 



OCL FOR MACRO PROCESSOR 

OCL statements used to call the macro processor can be 
entered through the system input device or be called as a 
procedure from the source library. The OCL statements 
necessary to call the macro processor are shown in Figure 
14. The // COMPILE statement shown is only necessary 
when input is in a source library. 

SAMPLE PROGRAM 

This sample program uses the macro processor and the 
IBM System/3 Model 15 Basic Assembler Program: 5704- 
AS1 or 5704-AS2. The coding shown in Figure 15 pro- 
duces an object program. To use the program, you must 
link edit the object program and execute it. The macro 
processor can be used with any valid assembler on the IBM 
System/3 Model 15 and is not limited to use with the 
program product 5704-AS1 or 5704-AS2. 



Termination of the Sample Program 

The sample program terminates in one of two ways: 

1 . After successful completion of the program, EJ is 
displayed on the CRT. 

2. When an error occurs during processing, one of the 
following halts is displayed on the CRT. 

A1— if an error is returned from the system input 
routine. 

A2— if an error is returned from the printer routine. 

You respond to these halts by choosing option 2. 
EJ is then displayed on the CRT. 



Purpose of the Sample Program 

The sample program in Figure 15 is used to print input 
records entered from the system input device. It reads 
data records from the system input device and prints them 
on a line printer. Each printed line reproduces one input 
record. If the spooling function is active for this program, 
the input may have been read prior to running this program, 
and the output may be retrieved at any time convenient 
for you. 
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Any valid // FILE statement may be used. 
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Source statements with macro instructions. 
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Figure 14. OCL Statements for Using the Macro Processor 
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Figure 15 (Part 4 of 4). Sample Program 
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Macro Instructions Used in tlie Sample Program 



Fifteen macro instructions are used in this sample program. 
The macro instructions and their functions are: 

Macro Instruction 

$ALOC 

$OPEN 

$CLOS 

$DTFD 

$EOJ 

$READ 

$PUTP 

$DTFP 

SDTFO 

$RLSD 

SRLST 

SLOGD 

$LOG 

$LMSG 

$PUTD 



Function 

Allocates the printer file to this program. 

Opens the file after allocation. 

Closes the output file. 

Constructs the DTF for disk. 

Calls the end-of-job routine. 

Reads input records from the system reader. 

Prints output records on the printer. 

Constructs the DTF for the printer. 

Establishes the offsets for the printer and disk DTFs. 

Generates offsets for the system reader parameter list. 

Constructs the parameter list for the system reader. 

Generates offsets for the system log parameter list. 

Logs message on the system log device. 

Constructs the parameter list for the system log. 

Puts records to a disk file. 
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Appendix A: Error Information 
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Appendix B: Define the File Control Blocks 



The DTF provides information to the data management 
routines about files you use. You must provide one DTF 
for each file you use in a program. Certain fields serve the 
same purpose in all pre-open DTFs. (Pre-open DTFs are 
reformatted to post-open when they are opened by using 
the allocate and open macro instructions.) 

The figures in this appendix describe both the pre-open 
and post-open DTFs for unit record and disk devices. 



Figure 


DTF Described 


17 


MFCU 


18 


MFCM 


19 


1442 


20 


Line Printer 


21 


2501 


22 


Disk 


23 


Tape 


24 


Device Independent 


25 


CRT/Keyboard 


26 


3741 



The labels given to the fields in these figures are the labels 
generated by the offset macro instruction $DTFO. Dis- 
placements are hexadecimal numbers which refer to the 
rightmost byte of the field; length is specified in bytes. 
Addresses in the DTFs point to the leftmost byte of the 
referenced area. 
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Field 
Name 



Displacement 



Length 



Contents 



$DFDEV 

SDFUPS 
$DFAT1 



$DFAT2 



$DFCHA 
$DFCHB 
$DFARR 
$DFXRS 
$DFLRA 
$DFCMP 



5 
7 
9 
B 
D 
E 



Device code 

MFCU1 (primary liopper of MFCU) = X'FO' 
MFCU2 (secondary hopper of IVIFCU) = X'F8' 

External indicators 

Attribute byte 1 

Bit On Meaning 






Read 


1 


Print 


2 


Punch 


3 


Card image mode 



Attribute byte 2 

Bit On Meaning 



Device is system reader 

Multiple buffers 

EOF on multiple buffers 

/. or /& read on last input operation 

DTF has been opened 



Address of next DTF in backward chain 
Address of next DTF in forward chain 
Address recall register save area (return address) 
XR1 save area (contents of calling program register 1) 
Logical record address 
Completion code 

Code Meaning 



X'40' 

x'4r 

X'42' 



Successful completion 
Permanent error 
End of file indicator 



Figure 17 (Part 1 of 2). MFCU DTF 
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Field 

Name 

?t;i:)FOPc 



SDFsrs 
SorciA 

Sin f^UA 
SDFPN/\ 

snrpi A 

$DFNI() 
SDFO 
SL'FR 
SDFRSV 



Disnlacement i l"niil!i I 



10 
12 

14 
10 
■!8 
19 
1'\ 
IB 



In'JtC'steK fipki IS uspf"* I'm pte or'eri 1"* I'f 
Finiiip 17 (Piirt ? of ?). MF CU D I F 



lOR nH'l 



iNliimfuM ■! M )i 
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Field 
Name 



Displacement 



Length 



Contents 



$DFDEV 

$DFUPS 
SDFAT1 



$DFAT2 



$DFCHA 
$DFCHB 
$DFARR 
$DFXRS 
$DFLRA 
$DFCMP 



5 
7 
9 
B 
D 
E 



2 
2 
2 
2 
2 
1 



Device code 

MFCM1 (primary hopper of MFCM) = X'FO' 
IV1FCI\/I2 (secondary hopper of MFCIVl) = X'F8' 

External indicators 

Attribute byte 1 

Bit On Meaning 






Read 


1 


Print 


2 


Punch 


3 


Card image mode 


4 


DTF for IViFCIVl 


5 


Interpret mode 


6 


Print head 5 or 6 to be used 



Attribute byte 2 

Bit On Meaning 



Device is system reader 

IVIultiple buffers (data) 

EOF on multiple buffers 

/. or /& read on last input operation 

DTF has been opened 



Address of next DTF in bacl<ward chain 

Address of next DTF in forward chain 

Address recall register save area (return address) 

XR1 save area (contents of calling program register 1) 

Logical record address 

Completion code 

Code Meaning 

X'40' Successful completion 

X'41' Permanent error 

X'42' End of file 



Figure 18 (Part 1 of 2). MFCM DTF 
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Field 
Name 



$DFOPC 



$DFSTS 

$DFCIA 

$DFRDA 

$DFPNA 

$DFPTA 

$DFNIO 

$DFQ 

$DFR 

$DFRDL 

SDFPNL 

$DFPTL 

$DFPHS 

$DFIND 



Displacement 



10 
12 
14 
16 
18 
19 
1A 
IB 
1C 
ID 
IE 
IF 
20 



Length 



Contents 



Operation code 

Bit On 


1 
2 
3 
4 
5 
6 



Meaning 

Read 

Print 

Punch 

Defer operation 

Card image 

No feed 

Four tier printing 



Stacker select 

JOB 

Read I/O area address' 

Punch I/O area address' 

Print I/O area address' 

Number of lOBs' 

Q-byte (device address) 

R-byte 

Read length' 

Punch length 

Print length 

Print head select 

Indicator byte 

Bit On Meaning 



Previous operation was print 
Feed required before print 
Read already completed 
First-time bit for interpret 



' Indicates field is used for pre-open DTF. 
Figure 18 (Part 2 of 2). MFCM DTF 
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Field 
Name 



$DFDEV 
SDFUPS 
$DFAT1 



$DFAT2 



Displacement 



$DFCHA 
SDFCHB 
$DFARR 
SDFXRS 
SDFLRA 
$DFCMP 



SDFOPC 



5 
7 
9 
B 
D 
E 



Length 



Contents 



Device code X'50' 
External indicators 
Attribute byte 1 

Bit On Meaning 



Read 

Punch 

Card image mode 



Attribute byte 2 

Bit On Meaning 



Device is system reader 

Multiple buffers (data) 

EOF on multiple buffers 

/. or /& read on last input operation 

DTF has been opened 



Address of next DTF in backward chain 
Address of next DTF in forward chain 
Address recall register save area (return address) 
XR1 save area (contents of calling program register 1) 
Logical record address 
Completion code 

Code Meaning 



X'40' 


Successful completion 


X'41' 


Permanent error 


X'42' 


End of file 


Operation code 




Bit On 


Meaning 





Read 


1 


Print 


2 


Punch 


3 


Defer operation 


4 


Card Image mode 


5 


No feed 



Figure 19 (Part 1 of 2). 1442 DTF 
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Field 
Name 



Displacement 



SDFSTS 


10 


SDFCIA 


12 


$DFRDA 


14 


$DFPNA 


16 


$DFNIO 


19 


$DFQ 


1A 


$DFR 


IB 


$DFPNL 


ID 



Length 



2 
2 
2 
3 
1 
1 
2 



' Indicates field is used for pre-open DTF. 
Figure 19 (Part 2 of 2). 1442 DTF 



Contents 



Stacker select (MFCU, MFCM, 1442) 

lOB addiess' 

Read I/O area address* 

Punch I/O area address' 

Number of lOBs' 

Q-byte (device address) 

R-byte 

Punch length 
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Field 
Name 

$DFDEV 



SDFUPS 
SDFATI 



$DFAT2 



SDFCHA 
$DFCHB 
$DFARR 
SDFXRS 
SDFLRA 
SDFCMP 



$DFOPC 



SDFSKB 
$DFSPB 
$DFSKA 
$DFSPA 



Dispiacement 





5 
7 
9 
B 
D 
E 



10 
11 
12 
13 



Length 

1 



2 
2 
2 
2 
2 
1 



Contents 

Device code 

Code Meaning 

X'EO' 1403 

X'lr 3284 

External indicarors 

Attribute byte 1 

Bit On Meaning 



1 



Print 



Attribute byte 2 

Bit On Meaning 



Halt on unprintable character 
DTF has been opened 



Address of next DTF in backward chain 

Address of next DTF in forward chain 

Address recall register save area (return address) 

XR1 save area (contents of calling program register 1) 

Logical record address 

Corn|)letion code 

Code Meaning 

X'40' SuccRSstuI completion 

X'41' Permanent error 

X'42' End of file 

X'48' Overflow on the printei 

O|jeration code 

Bit On Meaning 

1 Pimt 

Line number to skip to before the print operation 

Number of lines to space before the print operation 

Line number to skip to after the print operation 

Number of lines to space after the print operation 



Figure 20 (Part 1 of 2). Line Printer DTF 
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Field 








Name 


Displacement 


Length 


Contents 


$DFPQ 


14 


1 


Q-byte (device address) 


$DFPR 


15 


1 


R-byte 


$DFPIB 


17 


2 


lOB address' 


SDFPIO 


19 


2 


I/O area address' 


SDFPRL 


IB 


2 


Record length 


SDFOVF 


1C 




Overflow line number' 


$DFLP 


ID 




Lines per page' 


SDFPOS 


IE 




Position counter 


SDFMSK 


IF 




Maximum skip value' 


$DFPGS 


20 




Page size save area 



' Indicates field is used for pre-open DTF. 
Figure 20 (Part 2 of 2). Line Printer DTF 
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Field 
Name 



$DFDEV 
$DFUPS 
SDFATI 



$DFAT2 



$DFCHA 
SDFCHB 
SDFARR 
$DFXRS 
$DFLRA 
SDFCMP 



$DFOPC 



Displacement 



Length 



9 
B 
D 

E 



2 
2 
2 
2 
2 
1 



Contents 



Device code X'38' 
External indicators 
Attribute byte 1 

Bit On Meaning 



Read 

Card image mode 



Attribute byte 2 

Bit On Meaning 



2 
3 

4 
6 
7 



Device is system leader 
Multiple buffers are being used 
End-of-file on multiple buffers 
/. or /& was read 
DTF has been opened 



Address of next DTF in backward chain 

Address of next DTF in forward chain 

Address recall register save area (return address) 

XR1 save area (contents of calling program register 1) 

Logical record address 

Completion code 

Code Meaning 

X'40' Successful completion 

X'41' Permanent error 

X'42' End of file 

Operation code 

Bit On Meaning 






Read 


3 


Defer operation 


4 


Card image mode 


5 


No feed 



Figure 21 (Part 1 of 2). 2501 DTF 
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Field 








Name 


Displacement 


Length 


Contents 


$DFCIA 


12 


3 


lOB address' 


SDFRDA 


14 


2 


Read I/O area address' 


$DFNIO 


19 


5 


Number of lOBs' 


$DFQ 


1A 


1 


0-byte (device address) 


$DFR 


IB 


1 


R-byte 


$DFRDL 


1C 


1 


Read length 



' Indicates field is used for pre-open DTF. 
Figure 21 (Part 2 of 2). 2501 DTF 
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Field 
Name 



SDFDEV 



$DFUPS 
$DFAT1 



$DFAT2 



SDFCHA 
$DFCHB 
SDFARR 
$DFXRS 
$DFLRA 



Displacement 



Length 



5 
7 
9 
B 
D 



2 
2 
2 
2 
2 



Contents 



Device code:' 

R1 (removable disk - 5444, drive 1 ) = X'AO' 
F1 (fixed disl< - 5444, drive 1) = X'A8' 
R2 (removable disk - 5444, drive 2) = X'BO' 
F2 (fixed disk - 5444, drive 2) = X'B8' 
D1 (5445, drive 1) = X'CO' 
D2 (5445, drive 2) = X'C8' 
D3 (5445, drive 3) = X'DO' 
D4 (5445, drive 4) = X'DB' 

External indicators* 

Attribute byte l' 



Bit On 



Meaning 






Indexed 


1 


Consecutive 


2 


Direct 


3 


Multivolume 


4 


Input 


5 


Output 


6 


Update 


7 


Add 



Attribute byte 2' 

Bit On Meaning 



Multiple buffers 
DTF has been opened 



DTF chain pointer A (backward) 

DTF chain pointer B (forward)' 

ARR save area (return address) 

XR1 save area (contents of object program XR1 ) 

Address of logical record (shared I/O address of logical input record)' 



' Indicates field is used for pre-open DTF. 
Figure 22 (Part 1 of 7). Disk DTF (5704-SC1 only) 
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Field 
Name 



$DFCMP 



$DFOPC 



L 



$DFIOB 

$DFPRB 

$DFBKL 

$DFRCL 

$DFPTR 

$DFR01 

$DFXTA 

$DFIV1VF 

$DFR02 



Displacement 



11 

13 

15 
17 
19 
1A 
1C 
1C 
ID 



Length 



2 
2 
2 
1 
2 

(2) 
1 



Contents 



Completion code 

Code 

X'40' 
X'41' 
X'42' 
X'44' 
X'50' 
X'60' 
X'62' 
X'64' 
X'68' 
X'70' 
X'72' 



Meaning 

Normal completion 

Controlled cancel taken on permanent I/O error 

End of file (input) 

No record found (out of extent for direct files) 

Key field does not match key in update record 

Duplicate key on attempted load or add 

Keys out of sequence (attempted load or add) 

Key low for this volume or high for any volume 

Key low for this volume 

End of extent or end of read (output) 

Key high for last volume 



Completion codes other than X'40' are returned before the data manage- 
ment function is actually completed. 

Operation Code: 

Bit(s) On Meaning 






Get 


1 


Put/add or put/load 


2 


Put/update 


0,3 


Set new limits 



Pre-open address of I/O area' 
Post open address of lOB 

Address of current process lOB (dual I/O only; shared 
I/O— address of logical output record). 

Block length (length of data buffer)' 

Logical record length' 

Data block index (address of next record) 

Reserved 

Data start extent 

Address of direct MVF extent table' 

Reserved 



' Indicates field is used for pre-open DTF. 
Figure 22 (Part 2 of 7). Disk DTF (5704-SC1 only) 
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Field 
Name 



Displacement 



Length 



Contents 



$DFXTB 
SDFNUM 
$DFSWA 
$DFNAM 
$DFAT3 



$DFAT4 



$DFAT5 

SDFSEC 

$DFWAA 

$DFWAB 

$DFWAC 

$DFWAD 

$DFR04 

SDFRMA 

SDFROe 

SDFRMB 



IF 
IF 
20 
28 
29 



2A 



2B 
2C 
2D 
2E 
2F 
30 
31 
34 
35 
38 



2 

(2) 
1 
8 
1 



3 
1 
3 



Data end extent (disk address) 

Number of extents (direct MVF)' 

Scheduler work area format— 1 label sequence number 

File name' 

Attribute byte 3' 

Bit On Meaning 




1 
2 
3 
4 
5 
6 
7 



Addrout 

Ordered load 

Random 

Limits 

End of limits — call to open 

Force end of volume — call to close 

Online multivolume 

Reserved 



Attribute byte 4' 

Bit On Meaning 

Compiler access method 

1-7 Reserved 

Attribute byte 5 (Bits 0-7 are reserved)' 

Number of sectors to write (split) 

Work area A (disk) 

Work area B (disk) 

Work area C (disk) 

Work area D (disk) 

Reserved 

Work area, length of first part of overlap record 

Reserved 

Work area, length of second part of overlap record 



' Indicates field is used for pre-open DTF. 
Figure 22 (Part 3 of 7). Disk DTF (5704-SC1 only) 
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Field 

Name 

SDFNOI 



$DFND2 



$DFND3 



$DFR07 

$DFR08 

$DFNXR 

$DFSPC 

$DFR09 

$DFIOA 

$DFDAT 



Displacement 



39 



3A 



3B 



3C 

3D 

41 

42 

43 

46 

48 



Length 
1 



End of Disk DTF for consecutive output 



Contents 



Indicator byte 1 

Bit On Meaning 

0-3 Reserved 

4 Pseudo-get 

5 High key loaded (indexed output - IVIVF) 

6 Low key was found 

7 Buffer has been written 

Indicator byte 2 

Bit On Meaning 




1 
2 
3 

4 
5 
6 
7 



Indexed random update - first time indicator 

First record on new volume 

MVF end of file 

End of all MVF files 

Empty file (skip initial index search) 

Previous operation was add 

End of file has been reached 

EOF on this get (limits not set) 



Indicator byte 3 

Bit On Meaning 

Index contains adds or new entries 

1-3 Reserved 

4 Records added 

5 Out of sequence add (key sort needed) 

6 Current process buffer contains adds 

7 Current process buffer contains updates 

Reserved 

Reserved area 1 (5444 only) 

Disk address of next record (CSDD) 

IMumber of tracks in cylinder 

Reserved 

Disk address save area 

Pointer to current index entry. 



Figure 22 (Part 4 of 7). Disk DTF (5704-SC1 only) 
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Fieid 
Name 

SDFRU) 

SOf R1 I 

SDFEOF 



Dispiacensent 



49 
■I A 
4D 



Lengtii 

I 
1 
3 



Contents 



Reserved 

Reserved area 1 byte (5444 only) 

Disk address of logical end of file (CSD) 



End of Disk DTP for consecutive input ,uid update 

(3) 



$DFNXK 
$DFKPR 
SDFKAD 
SDFKCR 



4D 
4F 
51 
53 



Fnd of Disk DTF for direct 
SDFCUR 



SDFHI 

$DFR12 

SDFKXA 

SDFKBF 

SDFKL 

SDFR13 

SDF KXI^ 

SDFKD 

SDFBLX 

$DFR14 

SDFFLX 

$DFR15 



53 
53 
54 
56 
58 
5A 
5B 
5E 
60 
61 
62 
64 
65 



(2) 

(2) 

) 

2 
2 
2 
I 



Disk address of logical end of index (CSD) 
Pointer written index (pointer to next liuffer entry) 
Address of user's key area' 
Address of key in core (direct) 



Address of current key (index) 

Aflrlress of high key (limits) 

Reserved 

Stait extent ol index (disk address of first track) 

Aridress of mdex IF)B 

Key length 

Resei ved 

Oisi' addiess (,ii end ol mdex (CSD) 

Dis|)lacenif'nr >' i !>y in lecord' 

Index hinck si^e 

Reserved 

Disk adilress ol slait of indi'x (5445) 

Reseived 



' Indicates field is used for pre-open DTF. 
Figure 22 (Part 5 of 7). Disk DTF (5704-SC1 oniy) 
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Field 








Name 


Displacement 


Length 


Contents 


$DFDTX 


67 


2 


Start of disk track index (5445) disk address 


$DFABF 


69 


2 


Address of add index lOB 


$DFAPR 


6B 


2 


Add index buffer pointer 


End of Disk DTF for index sequential input output, and update 


$DFMIX 


6D 


2 


Address of in-core index (random)' 


$DFLOW 


6F 


2 


Address of low key (limit) 


End of Disk DTF for input or update with limits 


$DFLST 


6F 


(2) 


Address of last key (indexed sequential) 


$DFHAD 


71 


2 


Address of high add key bucket' 


$DFLOT 


71 


(2) 


Address of save area for current key' 


SDFHPK 


73 


2 


Address of high primary key 


$DFBYT 


75 


2 


Number of bytes in in-core index' 


End of Disk DTF for index random input and update 


SDFAPT 


77 


2 


Pointer to next record in add buffer 


$DFR16 


78 


1 


Reserved 


$DFR17 


79 


1 


Reserved area 1 byte (5444 only) 


$DFKXP 


7C 


3 


Disk address of end of primary index 


End of Disk DTF for index random add, retrieve add, and update add 


$DFSLP 


7E 


2 


Save area for last index disk pointer 


$DFR18 


7F 


1 


Reserved 


$DFSLA 


82 


3 


Save area for last index disk address 


End of Disk DTF for index sequential add and update add 



' Indicates field is used for pre-open DTF. 
Figure 22 (Part 6 of 7). Disk DTF (5704-SC1 only) 
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Field 
Name 



$DFSTA 

SDFSEQ 

SDFNXT 

$DFF1S 

SDFFI 

$DFAR1 

SDFXR1 

$DFKEY 

$DFTAB 

SDFENT 

$DFVOL 



Displacement 



1 



84 
85 
86 
87 
C6 
C8 
CA 
CC 
CE 
DO 
D1 



Length 



2 
1 
1 
1 
63 
2 
2 
2 
2 
2 
1 



Contents 



Multivolume file table pointer 

Volume sequence number of current volume 

Volume sequence number of next volume 

Start of format-1 

Format-1 save area 

EOV save area 

EOV save area 

Address of high key from Format-7 

Address of multivolume information table 

Number of entries in in-core index 

Number of volumes online 



End of Disk DTF for multivolume file processing 



Figure 22 (Part 7 of 7). Disk DTF (5704-SC1 only) 
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Field 
Name 

SDFDEV 



Displacement 



SDFUPS 



$DFAT1 



Length 



li'-- /' 



SiDFCi 

I 

Figun: 22a (Pa'i 



5 



2 



Contents 



Device code:' 

R1 (simulation area, drive 1) - X'AO' 
Fl (simulation area, drive 1) = X'A8' 
R2 (simulation area, drive 2) = X'BO' 
F2 (simulation area, drive 2) = X'B8' 
D1 (3340 drive 1) = X'CO' 
D2 (3340 drive 2) - X'C8' 
D3/D31 (3340 drive 3) - X'DC or 

(3344 drive 3, logical unit 1) = X'DO' 
D4/D4 I (3340 drive 4) - X'DB' or 

(3344 drive 4, logical unit 1) = X'DB' 
D32 (3344 drive 3, logical unit 2) ■= X'DI ' 
r)33 (3344 drive 3, logical unit 3) - X'D2' 
D34 (3344 drive 3, logical unit 4) = X'D3' 
D42 (3344 drive 4, logical unit 2) - X'D9' 
D43 (3344 drive 4, logical unit 3) = X'DA' 
044 (3344 drive 4, logical unit 4) - X'DB' 

i lixternal indicatorb' 



Attribute byle 1 



Bit On 



Meaning 






Indfxed 


1 


Consecutive 


2 


Diiect 


3 


Muitivoluine 


4 


input 


6 


Uutpul 


6 


ijpdate 


7 


Add 


Attribute 


)yte 2'' 


Bit On 


Meaning 





Device independent DTF 


1 


DTF ciilocated 


7 


Device isSYSIN 


3 


Multiple buffers data 


4 


Deterred open 


5 


F.OV - Close ignored bit 


6 


EOV Call close 


/ 


Opened 



DTF chain poinier A (backward) 



isH iui file tipeo D I"! 

o! /■■ D ^1: OTF (5704-SC2 o.iSyl 
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Field 
Name 



$DFCHB 
SDFARR 
$DFXRS 
$DFLRA 
$DFCMP 



$DFOPC 



SDFIOB 

$DFPRB 

$DFBKL 
SDFRCL 
SDFPTR 



Page of GC21 -7608-2 
Issued 29 September 1978 
ByTNL; GN21-5649 



Displacement 



7 
9 
B 
D 
E 



11 

13 

15 
17 
19 



Length 



Contents 



DTF chain pointer B (forward)' 

ARR save area (return address) 

XR1 save area (contents of object program XR1) 

Address of iogicai record (shared I/O address of logical input record)' 

Completion code : 

Code Meaning 

XOO' Record not found (requested key low) 

X'40' Successful completion 

X'41' Permanent error 

X'42' End of file 

X'44' No record found 

X'50' Update key not equal to key 

X'60' Duplicate key on load or add 

X'62' Keys out of sequence on load or add 

X'64' Key low for this volume or high for any volume 

X'68' Key low for this volume 

X'70' End of extent or end of reel 

X'72' Key high for last volume 

Completion codes other than X'40' are returned before the data man- 
agement function is actually completed. 



Operation code: 




Bit(s) On 


Meaning 


X'30' 


Get 


X'40' 


Put/update 


X'60' 


Put/add or put/load 


X'90' 


Set new limits 



Pre-open address of I/O area' 
Post open address of lOB 

Address of current process lOB (dual I/O only ; shared 
I/O — address of logical output record). 

Block length (length of data buffer)' 

Logical record length' 

Data block index (address of next record) 



' Indicates field used for pre-open DTF, 
Figure 22a (Part 2 of 7). Disk DTF (5704-SC2 only) 
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Field 




Name 


Displacement 


$DFSEG 


1A 


$DFXTA 


1C 


SDFMVF 


1C 


$DFQB 


ID 


SDFXTB 


IF 


SDFNUM 


IF 


SDFSWA 


20 


SDFNAM 


28 


SDFAT3 


29 



$DFAT4 



SDFAT5 



2A 



2B 



Length i Contents 



(2) 

1 

2 
(2) 

1 

8 

1 



i-iie snare segment number 

D if, address of start ot data 

Address of direct MVF extent table' 

Device independent Q code 

sK address of end of data 

Number of extents (direct MVFj' 

Si-ntauler work area format-1 label sequence number 

F-c name' 

Attiibute byte 3' ■ 

Bit On Meanmg 



Addrout 

Ordered load 

Random 

Limits 

End of limits — call to open 

Force end of volume — call to close 

Online multivolume 

Reserved 



Att Dute byte 4 



Bit On 



Meaning 










Compiler access method 


1 






Bypass direct file clear 


o 

c 






3340s supported 


3 






No verify (main data area) 


4 -6 






Reserved 


7 






Consecutive add from start of file 


Attribute 


byte 


5 


1 . 


Bit On 






Meaning 



Format-1 for this DTF 

File share 

Copying a PTAM file 

External buffers 

External buffers closed 

IVIultivolume file share support 

CCP task 

Reserved 



' Indicates field used for pre-open DTF. 
Figure 22a (Part 3 of 7). Disk DTF (5704-SC2 only) 
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Page of GC2 1-7608-2 
Issued 29 September 1978 
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Field 
Name 



SDFSEC 
$DFWAA 

SDFWAB 

SDFWAC 

$DFWAD 

$DFR04 

$DFR06 

$DFRMA 

SDFRMB 

SDFNDI 



$DFND2 



$DFND3 



Displacement 



2C 
2D 

2E 
2F 

30 
31 
32 
35 
38 
39 



3A 



3B 



Length 



Contents 



Number of sectors to write Ispiit) 
Work area A (disk) 

Work area B (disk) 

Work area C (disk) 

Work area D (disk) 

Reserved 

Reserved 

Work area, lengtfi of first pa>t of overlap record 

Work area, length of second part of overiap record 



Indicator byte 1 : 
Bit On 


1 

2 
3 
4 
5 
6 
7 

Indicator byte 2 : 
Bit On 


1 
2 
3 
4 
5 
6 
7 

Indicator byte 3 : 

Bit On 


1 
2 
3 
4 
5 
6 
7 



Meaning 

Buffer lb fv/iu!t of scan 'end 

Switch butters or pcnTers m subroutine 

Update ,)<:'' ; -s i" snarsj DTF 

PartiaMv fiii-J ad.i buffer ivritten 

Pseudo ije! 

High key 'oa ;pff iindaxed output — MVF) 

Low key was round 

Buffer has DPen written 

Meaning 

Indexed ■ ji^dom update - first time indicator 

First reco'C on new vi.i^ume 

MVF end of '.i" 

End of ay Mv'f f;!es 

Empty fi'f isKip initid! :ndex search) 

Previous ^loe .jtion was add 

End of file has t:)ec- rn^iched 

EOF on tHi'. got (iiniitb not set) 



Meaning 

Current process buffer contains update 
Added entries in input index buffer 
Records m add buffer were updated 
End of data in input buffer - indexed 
Records added 

Out of sequence add (key sort needed) 
Current process buffer contains adds 
New entries in add iniJex buffer 



' Indicates field is used for pre-open DTF. 
Figure 22a (Part 4 of 7). Disk DTF (5704-SC2 only) 
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Issued 29 September 1978 
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Field 
Name 



$DFWAE 

$DFPUN 

$DFNXR 

$DFSHR 

SDFIOA 

SDFDAT 

SDFNDB 



$DFR11 



Displacement 



3C 
3D 
41 
43 
46 
48 
49 



4A 



Length 



Contents 



Work area E (disk) 

Physical unit simulation area only 

Disk address of next record (CSDD) 

Address of file share DTP 

Disk address save area 

Pointer to current index entry 

Indicator byte 5 



Code 



1 

2- 7 



Meaning 

Get has not been done 

Do not flush buffers in close 

Reserved 



Reserved (simulation area only) 



End of Disk DTF for consecutive output 



$DFEOF 



4D 



Disk address of logical end of file (CSD) 



End of Disk DTF for consecutive input and update 



$DFNXK 
$DFKPR 
$DFKAD 
SDFKCR 



4D 
4F 
51 
53 



(3) 
2 
2 
2 



Disk address of logical end of index (CSD) 
Pointer written index (pointer to next buffer entry) 
Address of user's key area' 
Address of key in core (direct) 



End of Disk DTF for direct 



$DFCUR 

$DFHI 

$DFR12 

$DFKXA 

SDFKBF 




Address of current key (index) 

Address of high key (limits) 

Reserved 

Start extent of index (disk address of first track) 

Address of index JOB 



Indicates field is used for pre-open DTF. 
Figure 22a (Part 5 of 7). Disk DTF (5704^C2 only) 
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Field 








Name 


Displacement 


Length 


Contents 


$DFKL 


5A 


2 


Key length' 


$DFND4 


5B 


1 


Indicator byte 4 

Code Meaning 

First key invalid in index buffer 

1 First add buffer not filled 

2 Add area already formatted 
3-7 Reserved 


$DFKXB 


5E 


3 


Disk address of end of index (CSD) 


$DFKD 


60 


2 


Displacement of key in record' 


SDFBLX 


61 


1 


Index block size' 


$DFR14 


62 


1 


Reserved 


$DFR15 


63 


1 


Reserved 


$DFFLX 


65 


2 


Disk address of start of index (main data area) 


$DFDTX 


67 


2 


Start of disk track index disk address (main data area) 


$DFABF 


69 


2 


Address of add index lOB 


SDFAPR 


6B 


2 


Add index buffer pointer 


End of Disk DTF for index sequential input output, and update 


SDFIVIIX 


6D 


2 


Address of in-core index (random)' 


$DFLOW 


6F 


2 


Address of low key (limit) 


End of Disl< DTF for input or i 


jpdate with limits 


$DFLST 


6F 


(2) 


Address of last key (indexed sequential) 


$DFHAD 


71 


2 


Address of high add key bucket' 


SDFHPK 


73 


2 


Address of high primary key 


SDFBYT 


75 


2 


Number of bytes in in-core index' 


End of Disk DTF for index ran 


dom input and update 



' Indicates field is used for pre-open DTF. 
Figure 22a (Part 6 of 7). Disk DTF (5704-SC2 only) 
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Field 
Name 



Displacement 



Length 



Contents 



$DFAPT 
$DFR16 
$DFR17 
$DFKXP 



77 
78 
79 
7C 



2 
1 
1 
3 



Pointer to next record in add buffer 

Reserved 

Reserved area (simulation area only) 

Disk address of end of primary index 



End of Disk DTF for index random add, retrieve add, and update add 



$DFSLP 
$DFR18 
$DFSLA 



7E 
7F 
82 



Save area for last index disk pointer 

Reserved 

Save area for last index disk address 



End of Disk DTF for index sequential add and update add 



$DFSTA 

SDFSEQ 

SDFNXT 

$DFF1S 

$DFF1 

SDFAR1 

SDFXRI 

SDFKEY 

SDFTAB 

SDFENT 

SDFVOL 



84 

85 

86 

87 

C6 

C8 

CA 

CC 

CE 

DO 

D1 



2 
1 
1 
1 

63 
2 
2 
2 
2 
2 
1 



Multivolume file table pointer 

Volume sequence number of current volume 

Volume sequence number of next volume 

Start of format-1 

Format-1 save area 

EOV save area 

EOV save area 

Address of high key from Format-7 

Address of multivolume information table 

Number of entries in in-core index 

Number of volumes online 



End of Disk DTF for multivolume file processing 



= igure 22a (Part 7 of 7). Disk DTF (5704-SC2 only) 
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Field 
Name 



$DFDEV 



$DFUPS 
$DFAT1 



$DFAT2 



$DFCHA 
$DFCHB 
$DFARR 
$DFXRS 
$DFLRA 
$DFCMP 



Displacement 



5 
7 
9 
B 
D 
E 



Length 



Contents 



Device code: 

T1 (tape unit 1) = X'60' 
T2 (tape unit 2) = X'68' 
T3 (tape unit 3) = X'70' 
T4 (tape unit 4) = X'78' 

External indicators 

Attribute byte 1 

Bit On Meaning 



1 


Consecutive 


2 


Direct 


5 


Output 



Attribute byte 2 

Bit On Meaning 



Multiple buffers (data) 
DTF has been opened 



Address of next DTF in backward chain 

Address of next DTF in forward chain 

Address recall register save area (return address) 

XR1 save area (contents of calling progrann register 1) 

Logical record address 

Completion code 

Code Meaning 

X'40' Successful completion 

X'41' Permanent error 

X'45' Skip a bad input block 

X'70' End of extent or end of reel 

X'90' Wrong length record on input — short 

X'91' Wrong length record on input — long 

X'FO' Option to error message 

X'FT Option 1 to error message 



Figure 23 (Part 1 of 4). Tape DTF 
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Field 








Name 


Displacement 


Length 


Contents 


$DFOPC 


F 


1 


Operation code 

Code Meaning 

X'04' Read forward 
X'06' Read backward 
X'08' Write 
X'OA' Write tape mark 
X'OB' Rewind 
X'OC Backspace file 
X'OD' Rewind and unload 
X'OE' Forward space file 
X'lC Backspace block 
X'1 E' Forward space block 
X'40' Variable length 
X'80' Fixed length 


SDFIOB 


11 


2 


Pre-open address of I/O area' 
Post-open address of lOB 


$DFPRB 


13 


2 


Address of process lOB 


$DFLIO 


13 


(2) 


Length of I/O area' 


$DFBKL 


15 


2 


Block length' 


$DFRCL 


17 


2 


Record length' 


$DFPTR 


19 


2 


Pointer to logical record in buffer 


$DFCRL 


IB 


2 


Current record length 


$DFBCT 


ID 


2 


Block count 


$DFR03 


IF 


2 


Reserved 


$DFSWA 


20 


1 


Scheduler work area format— 1 index number 


$DFNAM 


28 


8 


File name' 



' Indicates field 
Figure 23 (Part 2 



is used for pre-open DTF. 
of 4). Tape DTF 
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Field 
Name 



Displacement 



Length 



Contents 



$DFAT3 



29 



$DFAT4 



2A 



$DFAT5 
SDFHTC 



2B 
2C 



Attribute byte 3 
Bits 5 are record format bits 

Bit On Meaning 

Fixed length 

1 Variable length 

2 Unblocked recor(Js 

3 Blocked records 

4 Spanned records 

5 ASCII format D. 

6 ASCII data management present (pre-open) 

7 ASCII file (post-open) 



Attribute byte 4 

Bit On 

0,1 

1 
2 
3 
4 
5 
6 
7 



Meaning 

Revi/ind at close 
Unload at close 
Leave at close 
Basic access method 
Standard label tape 
fj)f:ate mo.de 
No rnultivi'lume output 
Dl F close() by EOV 
F-ie(d opened on tliis 'ne 



Attribute byte 5 (Bits 7 are reserved) 

Error halt code 

Code Meaning 

X'lO' No get operation code 

X'l r Wrong lengtli record on input 

X'12' Wrong length block 

X'20' No put operation code 

X'2r Wrong length record on output 

X'40' Permanent tape write error at close 

X'41' Wrong block count 

X'50' Permanent tape read error at close 

X'60' No file statement 

X'6r File not allocated 

X'62' Not enough buffer space 

X'70' No basic operation code 



Figure 23 (Part 3 of 4). Tape DTF 
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Field 
Name 



$DFSQU 
$DFOST 



$DFWRA 

SDFWRB 

$DFWRC 

$DFWRD 

SDFR05 

SDFNDI 



SDFND2 

$DFHSA 

$DFSR1 

$DFSVD 

$DFSVE 



Displacement 



2D 
2E 



30 
32 
34 
36 
38 
39 



3A 
3C 
3E 
40 
42 



Length 



Contents 



Format— 1 sequence number 

ASCII buffer offset byte 

Code Meaning 

X'80' Offset is 4 bytes for block length 

X'OO' No offset specified 

Bits 1-7 are reserved for offsets of 0-99. 



Work area 


A 




Work area 


B 




Work area 


C 




Work area 


D 




Reserved 






Indicator 


byte 1 




Bit On 




Meaning 







lOB not waited on 


1 




Truncated block 


2 




Empty variable block 


3 




Error reading trailer label 


4 




Write trailer label 


5 




DTF closed by EOV 


6 




EOV return via open 


7 




No end of file reached 



Indicator byte 2 (bits 0-7 are reserved) 

Halt routine save area 

EOV register 1 save area 

EOV chain DTF address save area 

EOV save area 



Figure 23 (Part 4 of 41. Tape DTF 
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Field 
Name 



$DFDEV 
$DFUPS 
$DFAT1 



Displacement 



$DFAT2 



SDFCHA 
$DFCHB 
SDFARR 
$DFXRS 
$DFLRA 
$DFCMP 




1 
2 



5 
7 
9 
B 
D 
E 



Length 



2 
2 
2 
2 
2 
1 



Contents 



Device code X'40' 
External indicators 
Attribute byte 1 

Bit On Meaning 






Indexed 


1 


Consecutive 


2 


Direct 


3 


IViultivolume 


4 


Input 


5 


Output 


6 


Update 


7 


Add 



Attribute byte 2 

Bit On Meaning 



Device independent DTF 
Multiple buffers (data) 
/& read on last input operation 
DTF has been opened 



Address of next DTF in backward chain 

Address of next DTF in forward chain 

Address recall register save area (return address) 

XR1 save area (contents of calling program register 1) 

Logical record address 

Completion code 

Code Meaning 

X'40' Successful completion 

X'41' Permanent error 

X'42' End of file 

X'70' End of extent or end of reel 



Figure 24 (Part 1 of 5). Device Independent DTF 
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Field 
Name 



$DFOPC 



$DFIOB 

SDFPRB 

$DFBKL 

$DFRCL 

SDFPTR 

$DFPOV 

$DFR01 

$DFXTA 

$DFQB 

$DFR02 

$DFBCT 

$DFXTB 

$DFSWA 

$DFNAM 

$DFAT3 



Displacement 



11 

13 
15 
17 
19 
1A 
1A 
1C 
ID 
ID 
ID 
IF 
20 
28 
29 



Length 



2 

2 

2 

2 

1 
(1) 

2 

1 

(1) 
(1) 

2 

1 

8 

1 



Contents 



Operation code 

Bit On Meaning 



Get 
Put 



Pre-open address of I/O area' 
Post-open address of lOB 

Address of process lOB 

Block length' 

Record length' 

Pointer to logical record in buffer 
Printer overflow 
Reserved 

Disk address of start of data 
Q-byte (device address) 
Reserved 
Block count 

Disk address of end of data 
Scheduler work area format— 1 index number 
File name' 
Attribute byte 3 
Bits 0-5 are record format bits 
Bit On Meaning 




1 
2 
3 
4 
5 
6 
7 



Fixed length 

Not used 

Unblocked records 

Blocked records 

Spanned records 

ASCII format D 

ASCII data management present (pre-open) 

ASCII file (post-open) 



' Indicates field is used for pre-open DTF. 
Figure 24 (Part 2 of 5). Device Independent DTF 
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Field 
Wame 



$DFAT4 



Displacement 



2A 



Length 



Contents 



Attribute byte 4 



Bit On 



Meaning 









0,1 Rewind at close 








Unload at close 








1 Leave at close 








2 Basic access method 








3 Standard label tape 








4 Locate mode 








5 No multivolume output 








6 DTF closed by EOV 








7 Reel opened on this file 


$DFAT5 


2B 


1 


Attribute byte 5 (Bits 0-7 are reserved) 


SDFHTC 


20 


1 


Error halt code 

Code Meaning 

X'10' No get operation code 

X'1 1' Wrong length record on input 

X'12' Wrong length block 

X'20' No put operation code 

X'21' Wrong length record on output 

X'40' Permanent tape write error at close 

X'4r Wrong block count 

X'50' Permanent tape read error at close 

X'60' No file statement 

X'61' File not allocated 

X'62' Not enough buffer space 

X'70' No basic operation code 


$DFSEC 


20 


(1) 


Number of sectors to write (split) 


$DFWAA 


2D 




Work area A (disk) 


$DFSQU 


2D 


(1) 


Format— 1 sequence number (tape) 


$DFWAB 


2E 




Work area B (disk) 


$DFWAC 


2F 




Work area (disk) 


SDFWAD 


30 




Work area D (disk) 


$DFR04 


31 




Reserved 


$DFRMA 


34 


3 


Work area (disk) 


Figure 24 (Part 3 < 


3f 5). Device Indeo 


endent DTF 
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Field 
Name 



Displacement 



Length 



Contents 



SDFROe 

SDFRMB 

$DFND1 



$DFND2 



$DFND3 



$DFR07 

$DFHSA 

$DFR08 

$DFSR1 

$DFSVD 

SDFNXR 



35 
38 
39 



3A 



3B 



3C 
3C 
3D 
3F 
41 
42 



1 

(1) 
1 
2 
2 
1 



Reserved 



Work area (disk) 



Indicator byte 1 



Bit On 



Meaning 






iOB not waited on 


1 


Truncated block 


2 


Empty variable block 


3 


Error reading trailer label 


4 


Write trailer label 


5 


DTF closed by EOV 


6 


EOV return via open 


7 


No end of file reached 


icator byte 2 





Bit On Meaning 

Device=5444 Disk 

1 Device=5445 Disk 

2 Device=Tape 

3 Device=MFCM 
4,5 Reserved 

6 IOB waited on indicator 

7 Write indicator 

Indicator byte 3 

Bit On Meaning 



0-3 

4 

5-7 

Reserved 



Reserved 

Short record on unit record device 

Reserved 



Halt routine save area 

Reserved area 1 byte (5444 only) 

EOV register 1 save area 

EOV chain DTF address save area 

Disk address of next record 



Figure 24 (Part 4 of 5). Device Independent DTF 
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Field 
Name 



$DFSPC 
$DFSVE 
$DFR09 
$DFIOA 
$DFDAT 

$DFR10 
SDFR11 
$DFEOF 
$DFDVI 



Displacement 



43 
43 
44 
47 
49 

4A 
4B 
4E 
58 



Length 



1 

(1) 
1 
3 
2 

1 

1 

3 

10 



Contents 



Number of tracks in cylinder 

EOV save area 

Reserved 

Disk address save area 

Pointer to current index entry buffer pointer save 
area (split) 

Reserved 

Reserved area minus 1 byte (5444 only) 

Disk address of logical end of file 

Reserved for independent DTF 



Figure 24 (Part 5 of 5). Device Independent DTF 
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Field 
Name 



$DFDEV 
$DFUPS 
$DFAT1 

$DFAT2 



$DFCHA 
$DFCHB 
SDFARR 
$DFXRS 
SDFLRA 
SDFCMP 



Displacement 



5 
7 
9 
B 
D 
E 



Length 



Contents 



Device code X'10' 

External indicators 

Attribute byte 1 
Not used 

Attribute byte 2 

Bit On IVIeaning 

Device independent DTF 

1 DTF has been allocated 

2 Device is system input device 

3 Multiple buffers (if this bit is off, it indicates 
the first entry to CRT data management) 

7 DTF has been opened 

Address of the next DTF in backward chain 

Address of next DTF in forward chain 

Address recall register save area (return address) 

XR1 save area (contents of calling program register 1) 

Logical record address 

Completion code 

Code Meaning 

X'40' Successful completion 

X'41' Permanent error 

X'42' End of file indicator 



Figure 25 (Part 1 of 2). CRT/Keyboard DTF 
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Field 








Name 


Displacement 


Length 


Contents 


SDFOPC 


F 


1 


Operation code 

Bit On Meaning 

None No operation 

Input only 

0,1 Output/Input, Put/Get 
0,3 Input on request 
0,1,2,3 Clear zone portion of OPC 

1 Output only 

5 Do not blank buffer before operation 
4,5,6,7 Clear numeric portion of OPC 


$DFCLB 


11 


2 


Length of data, output 


$DFCSB 


13 


2 


Start position, output 


$DFCRA 


15 


2 


Address of data, input 


$DFCLI 


17 


2 


Length of data, input 


SDFCSI 


19 


2 


Start position of input 


$DFCQE 


1A 


1 


Console queue element (CQE) 


SDFECB 


1A 


(1) 


Console queue element ECB 


SDFQCB 


21 


7 


Console queue element Q-code 


$DFREQ 


22 


1 


Console queue element request code 


$DFADR 


24 


2 


Address of DTF 



Figure 25 (Part 2 of 2). CRT/Keyboard DTF 
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Field 
Name 


Displacement 


Length 


Contents 


$DFDEV 





1 


Device code:* 
3741 = X'40' 




$DFUPS 


1 


1 


External indicators' 




SDFATI 


2 


1 


Attribute byte l' 

Bit On Meaning 

1 Consecutive 

4 Input 

5 Output 




SDFAT2 


3 


1 


Attribute byte 2' 

Bit On Meaning 

Device independent 

1 Allocated 

2 System input 

3 Multiple buffers 

7 DTF has been opened 




$DFCHA 


5 


2 


DTF chain pointer A (backward) 




$DFCHB 


7 


2 


DTF chain pointer B (forward)' 




$DFARR 


9 


2 


ARR save area (return address) 




$DFXRS 


B 


2 


XR1 save area (contents of object program XR1) 




$DFLRA 


D 


2 


Address of logical record' 




SDFCMP 


E 


1 


Completion code 

Code Meaning 










X'40' Normal completion 

X'41' Controlled cancel taken on permanent I/O error 

X'42' End of file (input) 



' Indicates field is used for pre-open DTF. 
Figure 26 (Part 1 of 2). 3741 DTF 
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Field 








Name 


Displacement 


Length 


Contents 








Completion codes other than X'40' are returned before the data manage- 








ment function is actually completed. 


$DFOPC 


F 


1 


Operation Code: 

Bit(s) On Meaning 

Get 

1 Put 


SDFIOB 


11 


2 


Pre-open address of I/O area' 
Post-open address of lOB 


SDFPRB 


13 


2 


Address of current process lOB 


$DFBKL 


15 


2 


Block length (length of data buffer)' 


$DFRCL 


17 


2 


Logical record length' 


$DFPTR 


19 


2 


Reserved 


$DFR01 


1A 


1 


Reserved 


SDFXTA 


IC 


2 


Reserved 


SDFMVF 


1C 


(2) 


Reserved 


$DFR02 


ID 


1 


Reserved 


SDFXTB 


IF 


2 


Reserved 


SDFNUM 


IF 


(2) 


Reserved 


$DFSWA 


20 


1 


Reserved 


SDFNAM 


28 


8 


File name' 



' Indicates field is used for pre-open DTF. 
Figure 26 (Part 2 of 2). 3741 DTF 
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Appendix C: Input/Output Blocks 



DISK INPUT/OUTPUT BLOCK 

You build the disk lOB by issuing the $IOBD macro 
instruction. If you use $RDD, $WRTD, or SWAIT in your 
program, you must use the $IOED macro instruction to 
assign the offset in the lOB. The format of the lOB and 
the labels assigned to the fields are shown in Figure 27. 
lOBs for the 5444 Disk Storage Drive, the 5445 Disk 
Storage, the 3340 Direct Access Storage Facility, and 
the 3344 Direct Access Storage are 30 bytes long. 
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Label 

SIBtCB 


Displacement 


Length 


Contents 


f^iuates foi all diivieos 


Wait/post byte byte 1 ot ihree-byte ECB 





1 


SIBCOIVI 


1 


1 


Completion code - byte 2 of ECB. 


SIBCMP 


2 


! 


The third byte of ECB A one-byte completion code indicating the stall's 






of the operation just performed. Yon should check this byte befoie 






assuming that the data ti ansfei has occurred. Before the wait routine is 






called, each bit in this i)yte has the following meaning: 








Bit On Meaning 








Seek has been started on tiie operation requested 








by the lOB. 








1 The operation requested is complete 








2 Data transfer is pending on this operation. 








3 Data transfer has been started on this operation. 








4 A wait occurs for this lOB 








5 If bit 7 is also on, there is an error on an associated 








lOB; if bit 7 IS off, a scan equal has been found. 








6 The scan is not satisfied. 








7 A ptMinancnt erroi has occuired on this lOB or an 








associated iOB. 








After the wait roLitine has finished, the code in this byte has the 








following meaning: 








Code Meaning 








X'40' SucceSbtiii coninletion 








X'4r Permanent I/O erroi. 








X'42' Scan iiOt satisfied. 








X'44' Scan equal found. 








X'45' PeiiTianeut eiroi on an associated IOB. 


SlbCHN 


6 


4 


Addiess of the, lUixt IOB in liae chain. lOBs are cliained only when tiie 
file requires more than oiic IOB. Ihis an.;a is always present, even when 
chaining is not used. Wlien the operation specified by this ICJB is 
complete, this area contains the disk address last used (cylinder/sector 
loi ttte 5444; head/record for the 5445). 


,5 IB On 


7 


1 


The Q byte of the start l./QISIO) command. You set this byte througl^ 
the SlOBD macro instruction. 


■rIBRB 


8 


1 


The Fi byte of the sta>; I/O comnioud. It further defines the oporaticn 
requested. Figure 28 shows tiie po.ssible R-byte settings for the SIO 








comirtand. 

..,. . - .-. - 



f lai'i* '" if«i' 1 of 4). Disk iOB Format 
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Label 



SIBEID 
$IBDAT 

$IBSNS 

$IBFLG 



$IBERR 

$iBTCB 
SIBWRK 



Displacement 



9 
B 



11 
12 



Length 



Contents 



ERP module displacement ID. 

Address of the leftmost byte of your data area. You provide this address 
Through the $IOBD macro instruction. 

The area used by the input./output supervisor to contain device status 
sense information The contents of this area are described in Figure 29. 

Indicates special handling required for I/O operations through the various 
bit settings. You set bits and 4 through the $IOBD macro instruction. 
If no special handling is required this byte must be set to X'OO'. The 
bit settings are: 



Bit On 



Meaning 

No recovery is to be attempted is a data check, missing 

address mark, no record found, or track condition 

check error condition occurs. 

No verification is to be done on write operations. 

No error logging is to be done if any disk I/O error 

should occur. Control is to be returned to the calling 

routine. 

Disk lOS should not use the C and S bytes in the lOB, 

but should pick up the F, C, and S bytes at the end of 

the lOB for use in this opeiation. This bit should be 

used only by the system control program. 

The calling routine is not using disk data management; 

therefore, this lOB is not associated with a DTF. 

There is no load I/O of the disk file data register 

(DFDR). 

Error logging is in progress. 

A data transfer operation involving an alternate track is 

m progress. 



The area used by disk lOS to count the number of retries required to 
complete the I/O request. 

Task control block (TCB) address. 

lOS partial completion code. 



Figure 27 (Part 2 of 4). Disk lOB Format 
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Label 



$IBFL2 



$IBCC 



$IBHH 



$IBCB 



$IBR 



$IBSB 



$IBN 



$IBNB 



Displacement 



13 



14 



15 



15 



16 



16 



17 



17 



Length 



(1) 



(1) 



Contents 



Flag byte for use with the 5445. The meanings of the bits are: 
Bit On Meaning 






Special seek 


1 


Super lOB 


2 


Not used (5704-SC1) 


2 3 


Specify operation (5704-SC2) 




where: X'11' Scan 




X'10' Write 




X'Or Read 




X'OO' Seek 


3 


Not used (5704-SC1) 


4 


Reserved 


5 


Not used (5704-SC1) 


5 


C/S address must be converted but not Q-byte 




(5704-SC2) 


6 


No seek 


7 


Long form lOB 



The hexadecimal value of the cylinder address where the operation 

is to begin (5445 only). 

You set this byte through the $IOBD macro instruction. 

The hexadecimal value of the head address where the operation is to 

begin (5445 only). 

You set this byte through the $IOBD macro instruction. 

The hexadecimal value of the cylinder address where the operation 

is to begin (5444 only). 

You set this byte through the $IOBD macro instruction. 

The hexadecimal value of the record address where the operation 

is to begin (5445 only). 

You set this byte through the $IOBD macro instruction. 

The hexadecimal value of the beginning sector address of the 

operation (5444 only). 

You set this byte through the $IOBD macro instruction. 

The number of records minus one, in hexadecimal, involved in the 

data transfer (5445). 

You set this byte through the $IOBD macro instruction. 

The number of sectors minus one, in hexadecimal, involved in the 

data transfer (5444). 

You set this byte through the $IOBD macro instruction. 



Figure 27 (Part 3 of 4). Disk lOB Format 
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Label 

SIBDAD 
$!BDCH 

SIBDTF 



Displacement 

19 
IB 

ID 



Length 

2 
2 



Contents 

Pointer to 5445 i>;n byte disk address. 

The disk data manayernent chain pointer (5444 and 544!j) It contains 
the addi :,.;:. of tire secorrd of the two K)Bs used lor douhl" buffer uiq 

The address of the I3TF associated with this lOB 



Figure 27 (Part 4 of 4). Disk lOB Format 



no 



I/O 
Operation 


SIO R-Byte 
Settings (Hex) 


Interpretation 


5444 Settings 


Control 




Seel< 


Read 


00 
01 
0? 
03 


Data 

Identifier 
Diagnostic 
Verify 


Write 


00 
0! 


Data 
Identifier 


Scan 


00 

' 

o:> 


Etiual 

Low or equal 

High or equal 


5445 Settings 


Control 


00 
01 


Seek 
f^ecalibrate 


Read 


00 
03 


Key-data 
Verify key-data 


Write 


00 


Key-data 


Scan 


00 
01 
02 


Key-data equal 
Key-data low or equal 
Key-data high or equal 



Figure 28. R-Byte Settings 



TIMER INPUT/OUTPUT BLOCK 

If you use the $SIT, $TOD, or $R IT macro instructions in 
your program, you must build the timer lOB by issuing the 
$TIOB macro instruction. The format of the timer iOB 
varies depending on whether DATE Y or DATE-N is speci- 
fied. 



Format of Tinner IOB When DA TE-Y is Specified 
Bytes Contents 



Format of Timer IOB When DA TE-N is Specified 
Bytes Contents 



1 


Reserved 


2-7 


Time 


8 


Return Code 


9-10 


Reserved 



1 


Reserved 


2-7 


Time 


8-13 


Date 



Input/Output Blocks 111 
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Device 



Byte 



5444 



5445 



Bit On 



indication 



I/O no-op (single only) 
Intervention required 
Missing address mark 
Equipment check 
Data check 
No record found 
Track condition check 
Seek check 



Scan equai 

Access arm at cylinder 
End of cyhnder 
Seek busy 
Hundred cylinders 
Device overrun 
Status address A* 
Status address B* 



Format error 

Intervention required 

Missing address mark 

Equipment check 

Data check 

No record found 

No-op 

Overrun 



Disk drive error 

Unsafe 

Seek 1 complete 

Seek 2 complete 

Data operation complete 

End of cylinder has been reached 

Scan equal 

Disk drive ID** 



•Indicates which drive on the 5444 had last data transfe 
Bits 6 7 00-Drive 1 

01- Drive 2 



3it 7 



-Drive 1 

1 -Drive 2 



Figure 29. Device Status Sense Informatii 
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Appendix D: Macro Instruction Summary Chart 



Figure 30 is a summary chart containing all valid macro 
processor instructions. The macro instructions are listed 
in alphabetical order. In addition to the name, three items 
are given for each macro instruction: 

• Format of the instruction with all valid operands 

• Function of the macro instruction 

• Maximum number of statements generated 

For more detailed information on any of the macro 
instructions, see Chapter 2: Macro Instruction Statements. 
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112.2 



Name of Macro Instruction 



Name] 



[Name] 



[Name] 



[Name] 



Name] 



[Name] 



SALOC 



[DTF-address] 



$CHK 



[CKL-address] 



$CKL 



DTF-address [.SKiP-Y/N] [,REQK-Y/N] 
[,RTN-Y/N] [,LAST-Y/N] 



SCOMN 



SCTLT 



IDTF-address] (,OPC-code] 



fDTFC 



lOBA-address, NiOB-number 
[,DEV-code] 

l,UP-maskl [,CHN-address] 
[,RCAD-address] l,OPC-code] 
],DEFER-Y/N] [,CARDI-Y/J^] 
[,PRINT4-Y/N^] [,FEED-Y/N_] 
[.STACKR-number] (.READA-addressl 
[, PUNCH A-address] [.PRINTA-address] 
I.READL-number] [.PUNCH L-number] 
[.PRINTL-number] [,PRHEAD-mask] 
[,ALIGN-Y/N] 



$DTFD 



AC-code,R EC L-number, N AM E-filename, 
BLK L-number, 10 -address 
l,DISK-5444/5445/3340] 
[,UP-mask] [,BUFNO-1_/2[ [,MVFN/Y] 
[,LIM-N/Y] [,0RD-N/Y1 [,BIN-N/Y[ 
[,CHN-address] [,RCAD-addressl 
[,ENT-number] [,MVFN-numberj 
(,KEYL-number] [,KEYD-number[ 
[,KEYA-address] [,MVFT-address] 
I.MSTX-address] [,IBLKL-number] 
[,ADKEY-address] [,EOVK-address] 
[,SHR-Y/N] [,EXTBUF-Y/N] 



I Figure 30 (Part 1 of 6). Macro Instruction Summary Chart 



[Name] 


SCLOS 


[DTF-address[ 



[Name[ 


SCQEP 


[KEY-number] 



[Name] 


SDATE 


ILABEL-address] 



Function 
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Maximum Num- 
ber of Statements 
Generated 



Assigns the file indicated by the DTF to your 
program. 

Tests for I/O operation completion in the 
check list. 

Generates an entry for the check list to be 
used by the check routine. 



Prepares the device for job termination. 

Generates equates. 

Generates a parameter list for a program func- 
tion key request. 

Issues control commands to the tape device. 
Retrieves system date. 
Builds a DTF for a card file. 



Builds a DTF for a disk file. 

The SHR-Y/N and EXTBUF-Y/N 
parameters apply only to Program Number 
5704-SC2. 



None 



10 



11 



33 



210 
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Name of Macro Instruction 



[Name] 



[Name] 



[Name] 



[Name] 



[Nan 



[Name] 



$DTFI 



NAME-filename.RECL-number.iO-address 
[,AC-!N/OUT] [,8LKL.-number] 
[,RCAD-address] [,BUFN0-l/2] 
[,CHN-address] [,UP-mask] 



Function 



Builds a DTF for a device independent file. 



$DTFK 



NAME-filename,RECL-number,IO-address 
[,AC-J_/0] [,RCAD-address] [,BUFN0-1_/2] 
[,CHN-address] [,UP-mask] 



Builds a DTF for a 3741 file. 



SDTFO 



[DISK-Y/N] [,TAPE-Y/N] 1,IND-Y/N] 
[,MFCU-Y/N] I.MFCM-Y/N] f,D3741-Y/N] 
[,D2501-Y/N] [,D1442-Y/N] [,D1403-Y/N] 
[,D3284-Y/N] [,CRT-Y/N] [,ALL-Y/N] 
[,FIELD-Y/N] 



Establishes labels for fields on a DTF. 



$DTFP 



RCAD address, IOBA-address,IOAA-address, 
OVFL-number,PAGE-number [,DEV-code] 
[,UP-mask] [HUC-Y/N] [,CHN-address] 
[,PRINT-Y/N] [,SKIPB-number] 
[.SPACEB-number] [.SKIPA-number] 
[,SPACEA-number] [,RECL-number] 



SDTFS 



[PUTDAT-address] [.PUTLOC-number] 
[,UP-mask] [,CHN-address] 
[.PUTLEN-number] [,OPC-code) 
[.GETDAT-address] [,GETLOC-number 
[.GETLEN-number] [,BLANK-Y/N] 



SDTFT 



NAME-filename,IO-address,BLKL-number, 
RECL-number [,UP-mask] [, AC-IN/OUT] 
[,CHN-address] [,BASIC-Y/N] 
[,RCAD-address] [, MODE-LOCATE/ MOVE 1 
[,MBUFF-Y/N] [.RECFM-code] 
[,LIOA-number] [,SPAIM-Y/N] [,C0DE-A/EJ 
[,OSET-B/number] [,END-code] [,MVF-Y/N 



Name ] $EOJ [CANCEL-NORMAL/IMMED/CONTRL] 



Builds a DTF for a printer file. 



Builds a DTF for a CRT file. 



Builds a DTF for a tape file. 



Terminates the job and returns control to the 
supervisor. 



Maximum Num- 
ber of Statements 
Generated 



16 



None 



33 



37 



67 



Name] $FIND NAME-module [,FIND-address] [.PACK P/S] 



Provides the disk address of a module in the 
O library. 



23 



[Name] 



$FTCH 



NAME-module name[,PACK-P/S] 



Figure 30 (Part 2 of 6). Macro Instruction Summary Chart 



Finds and loads an O module and passes 
control to it. 



21 



114 



Name of Macro Instruction 



[Name] 


$GETC 


[DEV-code] [.DTF-address] | ,EOF-address] 
[,ERR-address] [,OPC-Y/N] 
[,READL number] ],CARDI-Y/N] 
[.STACKR-number] 



Function 



Gets a record from a card file. 
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Maximum Num- 
ber of Statements 
Generated 

31 



[Name] 


$GETD 


1 [AC-code] 
1 [EBAC-code] 

[.DTF-address] ],ERR-address] 
[.EOF-address] [,NFR address] 
[ LSTV-address] 1 NOKY-address] 



[Name] 


SGETI 


[DTF-address] [.RCAD-address] 
[,ERR-address] (, EOF -address] 



Gets a record from a disk file via disk data 
management. 

The EBAC-code parameter applies only to 
Program Number 5704-SC2. 



Gets a record from a device independent file. 



46 



32 



Name] $GETK EOF-address [, DTF-address] [,ERR-address] Gets a record from a 3741 file. 



[Name] 


$GETS 


[DTF-address] I, GETDAT address] 
l.GETLEN-number] j.GETLOC-number ! 
l.BLANK-Y/JM] j ,OPC-IN/INR/N 1 
[, EOF-address] 



Gets a record from the CRT keyboard. 



48 



[Name] 


$GETT 


MOD ULE-name[, DTF-address] 
I.RCAD-addressI |,OPC-Y/N| 
[,ERR-addressj [, EOF-address] 



Gets a record from a tape file. 



35 



IName) 


$GPC 


[DEV-codej [, DTF-address] [.OPC-code] 

],DEFER-Y/N) |,CARDI-Y/N1 

[,PRINT4-Y/N] |,FEED-Y/N1 

1,ST AC KR -number 1 | ,READL-number I 

],PUNCHL-number] | ,PRI NTL-number i 

[.PRHEAD-mask] ], EOF-address] 

],ERR-address] 



Constructs a get, then a put interface to 
a card file. 



37 



IName] 


SIOBD 


[DISK-5444/5445/3340] [.CYL-number] 
[,SCTR-numberl ],HEAD-number I 
[,NUM-number] l.BUFF-address] 
[.Q-number] ],ERREC-IOS/USER ] 
[,LOG-Y/NJ |,VER-Y/N] | ,CHN-addressl 



Builds an lOB for a disk file. 



40 





$IOED 





Establishes labels for fields in the disk lOB. 



None 



[Name] 


SLMSG 


[FORMAT-codni |,COMP-code] 
[.HALT-code] ],SUBH-codel |,SEV-code] 
[,DEF-codel |,OPN0-Y/N] [,OPNl-Y/Nl 
1,0PN2-Y/I\I1 1,0PN3-Y/N1 jTLEN-number ! 
l.TADR-address] 



Generates loq list for halt message. Linkage 
to log may also be generated. 



12 



I Figure 30 (Part 3 of 6). Macro Instruction Summary Chart 
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Name of Macro Instruction 



'Name] 



Name] 



SLOAD 



SLOAD 



NAM E-module name J.FIND-address] 
[,L0AD-2/address] 1,USE-R/NR] 
l.PLIST-address] 1,PACK-P/S] 



FIND-address l,L0AD-2/address] 
1,PACK-P/S] 



[Name] 



SLWTO 



JName] 


SLOG 


[LIST-address] l,OPN0-address] 
J.OPNI -address) J,0PN2-address] 




SLOGD 





TLEN-number, TADR-address [.COMP-code] 
],HALT-code| [,SUBH-code] [,REPLY-Y/NJ 
[,RLEN-number| [,R ADR-address] 



Function 



Finds and loads or loads a previously found O 
module into main storage. 



Name] SOPEN JDTF-address 



Generates linkage to system log. 



Generates offsets for log lists. 



Generates parameter list tor write to operator 
or write to operator with reply function. 



Prepares a previously allocated file for data 
transfer. 



Maximum Num- 
ber of Statements 
Generated 

41 



29 



None 



15 



[Name] 



$PFKT 



ICQE-address] [,\A/AIT-Y/N] 
[,LABEL-address] 



Tests whether a program function key that 
was allocated by $PFKY has been pressed. 



14 



[Name] 



SPFKY 



[CQE-address] [,ERR-address] 



Request allocation of a program function 
key. 



22 



Name] 




[DTF-address] [,BLANK-Y/N] 1,0PC-Y/N] 
[.PUTDAT-address] [.PUTLEN-numberJ 
[.PUTLOC-number] [,GETDAT-addiess| 
l.GETLEN-number] [.GETLOC-number] 
l.EOF-address) 



PUT/GET operation through CRT data 
management. 



66 



[Name] 


SPUTC 


[DEV-codej [,DTF-address[ [,OPC-code] 
[,DEFER-Y/]^] [,PRINT4-Y/N[ 
[,FEED-Y/N] [.STACKR-number] 
[, PUNCH L-number] [.PRINTL-number ] 
[,PRHEAD-mask] [,ERR-address] 



I Figure 30 (Part 4 of 6). Macro Instruction Summary Chart 



Puts a record to a card file. 



[Name] 


$PUTD 


1 [AC-code] 1 
1 [EBAC-code]J 

[, DTF-address] [,ERR-address] 
(,EOX-address] [,DUP-address] 
[,SERR-address] [,KERR-address] 
[,UPD-Y/N) [,LSTV-addressl 
[,NOKY-address] [,HKER-address] 



[Name] 


$pufi 


[,DTF-address] [,RCAD-address] 
[,ERR-address] (,EOX-address] 



Writes a record on a disk file via disk data 
management. 

The EBAC-code parameter applies only to 
Program Number 5704-SC2. 



Puts a record to a device independent 
file. 



30 



67 



32 



116 



Name of Macro Instruction 



[Name! 


$PUTK 


[DTF-addiess] [.ERR-address) 



Function 



Puts a record to a 3741 . 
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Maximum Num- 
ber of Statements 
Generated 



[Namei 



$PUTP 



[DEV-codel [,DTF-address] (,PRINT-Y/I\J] 
[,SKIPB-number] [,SPACEB-number] ~ 
[.SKIPA-number] I.SPACEA-numbei i 
I.ERR-addressl [,OVFL-addressl 



Prints a record via printer data management. 



37 




IDTF-address] [,BLANK-Y/N_| [,OPC-Y/N] 
[,PUTDAT-address] [.PUTLOC-number] 
[.PUTLEN-numberJ 



Puts a record to the CRT via data management. 



38 



INamel 


SPUTT 


MODULE-name | ,DTF -address] 
I.RCAD-address] [,OPC-Y/N] 
[.LENAD-address] (, ERR-address] 



Puts a record to a tape file. 



33 



jName] 


$RDD 


IOB-address,CS-address,NSECT-number 
[,DISK-5444/5445/3340l 





Reads a record from a disl< file via the input/ 
output supervisor. 



19 



I Name] 



$RDT 



[DTF -address] [,RCAD-address) 
[,DIRECT-FORW/BACK] 



Reads a record from a tape file via basic 
tape data management. 



21 



liMamei $READ 



ILIST-address] [,OPC-code] l.EOF-address] 
i.EOJ-address] J, ERR-address] 



Generates linkage to system reader. 



32 



jNarnej 


$RIT 


]IOB-name] 1,CANCEL-Y/N ] 



Returns the amount of time remaining in a 
time interval. 





SRLSD 







Generates offsets in system reader parameter 
list. 



None 



Name] $RLST BUF 1 -address.WORK-address f,BUF2-address] 



Generates system reader parameter list, 
buffers, and work area. 



]Name] 


SROLL 


]INDEX-1/2) 



Generates linkage to rollout/rollin. This 
macro applies only to Program Number 
5704-SC1. 



17 



(Name] 


SSIT 


llOB-name] 1,TYPE-DEC/BIN/TU/T0D] 
[,ITYPE-REAL/WA IT/TASK] 



Sets a time interval. 



(Name] 


SSNAP 


ID-hex,START-address,END-address 



Prints the specified area of main storage on 
the system logging device. 



10 



]Name] 



$TIOB 



(DATE-Y/Nl 



Figure 30 (Part 5 of 6). Macro Instruction Summary Chart 



Generates a timer lOB. 
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Name of Macro Instruction 



[Name] 



$TOD 



[lOB-name] [,REF-Y/JN] 
[,TYPE-DEC/BIN/TU1 



Function 



Returns the time of day and the system date 
to the program. 



Maximum Num- 
ber of Statements 
Generated 



Name] 



$TRAN 



[TRL-address] 



Translates a record using the system translate 
routine. 



[Name] 



$TRL 



TO-address,FROM-address,LEN-number, 
TRT-address 



Name] STRTB [CODE-E/A] [,HEX-hex] 



Builds a parameter list to pass information to 
the system translate routine. 



Generates an EBCDIC to ASCII or an ASCII 
to EBCDIC translate table. 



258 



[Name] 



SWAIT 



[lOB-label] [,ERR-address] 



Waits for completion of a disk input/output 
operation. 



15 



'Name] 



SWRTD 



IOB-address,CS-address,NSECT-number 
[,DISK-5444/5445/3340] 



[Name] 



$WRTT 



[DTF-address] [,RCAD-address] 
|,OPC-Y/N] 



Name] 



SWTT 



[DTF-address) [,ERR-address] 
[,EOF-address] [,EOT-address] 
[,WLRS-address] [,WLRl.-address] 



Writes a record on a disk file via the input/ 
output supervisor. 



Writes a record to a tape file via the basic 
tape data management. 



Waits for completion of a basic tape data 
management I/O operation. 



19 



21 



43 



[Name] 



BXCTL 



NAME-module name[,LOAD-2/address] 
[,PACK-P/S] 



I Figure 30 (Part 6 of 6). Macro Instruction Summary Chart 



Finds and loads a module at a specified 
address and passes control to it. 



22 



118 



Index 



$ALOC (allocate space) macro instruction 23 

SCHK (check I/O completion) macro instruction 26 

$CKL (generate checklist) macro instruction 25 

$CLOS (prepare device for termination) macro instruction 26 

$COIVIN (common equates) macro instruction 27 

$CQEP (generate parameter list program function key) macro 

instruction 61 
$CTLT (control command for tape) macro instruction 54 
$DATE (obtain system date) macro instruction 19 
$DTFC (card DTP) macro instruction 28 
$DTFD (disk DTF) macro instruction 36 
$DTFI (device-independent DTF) macro instruction 56 
$DTFK (3741 DTF) macro instruction 48 
$DTFO (generate DTF offsets) macro instruction 27 
$DTFP (printer DTF) macro instruction 33 
$DTFS (CRT DTF) macro instruction 58 
$DTFT (tape DTF) macro instruction 49 
$EOJ (end-of-job) macro instruction 20 
$FIND (find directory entry) macro instruction 13 
$FTCH (load module pass control) macro instruction 16 
$GETC (card get interface) macro instruction 30 
$GETD (disk get interface) macro instruction 40 
$GETI (device-independent get interface) 

macro instruction 57 
$GETK (3741 get interface) macro instruction 48 
$GETS (get record from CRT/keyboard macro instruction 59 
$GETT (tape get interface) macro instruction 52 
$GPC (interface reading, punching and printing 

cards) macro instruction 32 
$10BD (input/output block disk) macro instruction 45 
$IOED (input/output block offsets) macro instruction 46 
$LMSG (parameter list message system log) 

macro instruction 11 
$LOAD (load module) macro instruction 13 
$LOG (linkage system log) macro instruction 12 
$LOGD (displacements system log) macro 

instruction 12 
$LWTO (parameter list WTO or WTOR) macro 

instruction 10 
$OPEN (prepare an I/O device) macro instruction 24 
$PFKT (test program function key pressed) macro 

instruction 62 
$PFKY (allocate program function key to program) 

macro instruction 61 
$PGS (put/get operation CRT data management) macro 

instruction 59 
$PUTC (card put interface) macro instruction 31 
$PUTD (disk put interface) macro instruction 44 
$PUTI (device-independent put interface) macro 

instruction 57 
$PUTK (3741 put interface) macro instruction 49 



$PUTP (printer put interface) macro instruction 34 
$PUTS (put record CRT data management) macro 

instruction 60 
$PUTT (tape put interface) macro instruction 53 
$RDD (read from disk) macro instruction 46 
$RDT (read from tape) macro instruction 53 
$READ (linkage system reader function) macro 

instruction 9 
$RIT (return interval time) macro instruction 20 
$RLSD (system reader parameter list offsets) macro 

instruction 8 
$RLST (system reader parameter) macro instruction 8 
$ROLL (rollout/rollin linkage) macro instruction 12 
$SIT (set interval timer) macro instruction 19 
$SNAP (snap dump main storage) macro instruction 18 
$SOURCE file 2 

$TIOB (timer lOB) macro instruction 19 
$TOD (return time and date) macro instruction 20 
$TRAN (interface translate routine) macro instruction 
$TRL (translate parameter list) macro instruction 17 
$TRTB (translate table) macro instruction 18 
SWAIT (wait disk IDS completion) macro instruction 
$WRTD (write to disk) macro instruction 47 
$WRTT (write to tape) macro instruction 54 
$WTT (wait tape I/O completion) macro instruction 
SXCTL (load module exchange control) macro 

instruction 17 



18 



47 



55 



access method 40 

allocate program function key to a program ($PFKY) 

allocate space ($ALOC) 23 

areas, simulation 35 



block 

disk input/output 106 

input output 106 

timer input/output 111 
block for disk ($IOBD), input/output 45 
block offsets ($tOED), input/output 46 
buffer storage requirements 

disk 37 

tape 51 
buffers 

double card device 29 

formatted 24 

initialized 24 

single card device 29 
byte settings, R 111 



61 



Index 119 



card (SDTFC), file for 28 

card device support 28 

card get interface {$GETC) 30 

card put interface ($PUTC) 31 

cards ($GPC), printing, punching, and reading interface 32 

chaining 

allocate space routine 23 
close routine 27 
DTFs 23 
open routine 24 
chart, summary, instruction, macro 112 
check for I/O completion ($CHK) 26 
check routine operation 26 
checklist ($CKL) 25 
close routine 
input 26 
output 26 
codes, macro instruction error 67 
coding conventions 1 
command for tape ($CTLT), control 54 
comments 3 

COMMON equates ($COMN) 27 
completion ($CHK), check for I/O 26 
completion ($WAIT), wait for disk lOS 47 
completion ($WTT), wait for tape I/O 55 
configuration, minimum system 4 
considerations, programming 7 
construct a card get interface ($GETC) 30 
construct a card put interface ($PUTC) 31 
construct a device independent get interface ($GETI) 57 
construct a device independent put interface ($PUTI) 57 
construct a disk get interface ($GETD) 40 
construct a disk put interface ($PUTD) 41 
construct a printer put interface ($PUTP) 34 
construct a tape get interface ($GETT) 52 
construct a tape put interface ($PUTT) 53 
construct a 3741 get interface ($GETK) 48 
construct a 3741 put interface ($PUTK) 49 
construct an interface for reading, punching, and 

printing cards ($GPC) 32 
continuation coding 3 

control ($FTCH), load a module and pass 1 6 
control ($XCTL), load a module and exchange 17 
control blocks, file 68 
control command for tape ($CTLT) 54 
CRT ($DTFS), file 58 

CRT data management ($PGS), put get operation 59 
CRT support 58 

CRT via data management ($PUTS), put a record 60 
CRT/keyboard 58 

CRT/keyboard ($GETS), get a record 59 
CRT/keyboard DTF 102 



data areas, main 35 

data management ($PGS), put get operation 

through CRT 59 
data management ($PUTS), put CRT record 60 
data management interface (tape basic) 
control 54 
read 53 
write 54 
data management routines 
card 30, 31 
CRT/keyboard 59, 60 
device independent 57 
disk 40, 41 
printer 34 
tape 52, 53 
data transfer, input/output file 24 
date ($DATE), obtain system 19 
date ($TOD), return time and 20 
date-N is specified, timer JOB 111 
date-Y is specified, timer JOB 111 
default value, definition 1 
define the file 

card ($DTFC) 28 
CRT ($DTFS) 58 
device independent ($DTFI) 56 
disk ($DTFD) 36 
file sharing 39 
multivolume 52 
printer ($DTFP) 33 
tape ($DTFT) 49 
3741 ($DTFK) 48 
define the file control blocks 68 
deleting macro instructions 4 
device ($OPEI\l), prepare I/O 24 
device independent DTF 97 
device independent get interface ($GETI) 57 
device allocation 24 
device independent ($DTFI), file 56 
device independent put interface ($PUTI) 57 
device independent support 56 
device support 
card 28 

CRT/keyboard 58 
device-independent 56 
disk 35 
general 22 
printer 33 
tape 49 
3741 48 
device termination ($CLOS), prepare 26 
devices supported 4 
devices, input and output 4 
directory entry ($FIND), find 13 
disk ($DTFD),file 36 
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disk device support 35 

disk DTF (5704-SC1 only) 79 
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disk get interface ($GETD) 40 

disk input/output block 106 

disk input/output supervisor interface 45 

disk lOB format 107 

disk lOS connpletion ($WAIT), wait 47 

disk put interface ($PUTD) 44 

disk routines 

get 40 
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read 46 
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write 47 
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display support 58 
DTF 
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CRT/keyboard 58 

device-independent 56 

disk 36 

printer 33 

tape 49 
DTF defined 
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field lengths 27 
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pre-open 24 
DTF descriptions 
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device-independent 97 
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MFCM 71 
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file control blocks, define 68 

file, define (see define the file) 

find (form I), load 13 

find a directory entry ($FIND) 13 

find parameter list after load execution 15 
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format of timer lOB 

DATE-N specified 1 1 1 

DATE-Y specified 1 1 1 
format, disk lOB 107 

function ($READ), linkage to system reader 9 
function key pressed ($PFKT), test for program 62 
function key request ($CQEP), parameter list for program 
function key support, program 61 
function key to a program ($PFKY), allocate program 61 
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general I/O support 22 
general SCP support 12 
generate a checklist ($CKL) 25 
generate a parameter list 

message on system log (SLMSG) 1 1 

program function key request ($CQEP) 61 
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generate a put/get operation through CRT data management 

($PGS) 59 
generate a system reader parameter list ($RLST) 8 
generate a translate parameter list ($TRL) 17 
generate a translate table ($TRTB) 18 
generate an interface to the translate routine ($TRAN) 18 
generate displacements for system log ($LOGD) 12 
generate DTF offsets ($DTFO) 27 
generate equates 27 

generate program function key request 61 
generate the linkage to the system log ($LOG) 12 
generate timer lOB ($TIOB) 19 
get 
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CRT/keyboard 59 

device-independent 57 

disk 40 
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3741 48 
get a record from the CRT/keyboard ($GETS) 59 
get input operation through CRT data management ($PGS) 59 
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halt/syslog routine 23 



end-of-job ($EOF) 20 
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generate 27 

labels 8 

system reader parameter list 8 
equates ($COMN), COMMON 27 
error codes, macro instruction 67 
error information 67 
exchange control ($SCTL), load module and 17 
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I/O completion ($CHK), check 26 
I/O completion ($WTT), wait for tape 55 
I/O device ($OPEN), prepare 24 
I/O support, general 22 
information, error 67 
input devices supported 4 
input/output block 
disk 106 
timer 1 1 1 
input/output block for disk ($IOBD) 45 
input/output block offsets ($IOED) 46 
input/output blocks 106 
input/output supervisor interface (disk) 
read 46 
wa it 47 
write 47 
input/output support 22 
input 

close routine 26 
open routine 24 
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delete macro 4 
macro 4 
macro (list of) 5 
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interface 
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card put 31 

device independent get 57 
device independent put 57 
disk get 40 
disk put 41 
printer put 34 

reading, punching, and printing cards 32 
tape get 52 
tape put 53 
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3741 get 48 
3741 put 49 
interrupt program 12 
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interval timer ($SIT), set 19 
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printer 33 
tape 50 
timer, build 19 
description 1 1 1 
format 111 
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description 106 
storage requirements 37 
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read 46 
write 47 
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key support, program function 61 
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keywords 1 



label restrictions 
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warning 27 
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line printer DTP 75 
linkage to the system log 12 
linkage to system reader function ($READ) 9 
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find parameter 14 
load parameter 16 
parameter 

find after load execution 15 
message on system log 1 1 
program function key request 61 
system reader offsets 8 
translate 17 
WTOorWTOR 10 
system reader parameter 8 
load a module and exchange control ($XCTL) 17 
load a module and pass control ($FTCH) 1 6 
load a module (SLOAD) 13 
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load parameter list description 16 
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log 
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linkage to the system 12 
parameter list for message on system 1 1 
log support, system 9 
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machine configuration 4 
macro instruction 

$ALOC (allocate space) 23 

SCHK (check I/O completion) 26 
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SCOMN (COMMON equates) 27 

SCQEP (generate parameter list program function key) 

$CTLT (control command for tape) 54 

SDATE (obtain system date) 19 

$DTFC (card DTF) 28 

$DTFD (disk DTF) 36 

SDTFI (device-independent DTF) 56 

$DTFK (3741 DTF) 48 

$DTFO (generate DTF offsets) 27 

$DTFP (printer DTF) 33 

$DTFS (CRT DTF) 58 

$DTFT (tape DTF) 49 

SEOJ (end-of-job) 20 

SFIND (find directory entry) 13 

$FTCH (load module pass control) 16 

$GETC (card get interface) 30 

SGETD (disk get interface) 40 

SGETI (device-independent get interface) 57 

$GETK (3741 get interface) 48 

SGETS (get record from CRT/keyboard) 59 
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$IOED (input/output block offsets) 46 
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SLOAD (load module) 13 
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SOPEN (prepare an I/O device) 24 
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SPUTP (printer put interface) 34 

SPLITS (put record CRT data management) 60 
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macro instruction (continued) 

$TIOB (timer lOB) 19 

$TOD (return time and date) 20 

STRAN (interface translate routine) 18 

$TRL (translate parameter list) 17 

STRTB (translate table) 18 

$WAIT (wait disk IDS completion) 47 

SWRTD (write to disk) 47 

$WRTT (write to tape) 54 
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macro instructions 

coding 1 

definitions 1 
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error codes 67 
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sample program 66 

summary chart 1 1 1 
macro processor 

overview 2 
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residence 4 

restrictions 7 
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obtain system date (SDATE) 19 
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input 24 
output 24 
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parameter list 
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log and/or message to operator 1 1 
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system log message 1 1 
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system reader 8 
translate routine 17 
write to operator 10 
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programming considerations 7 
put 

card 31 

CRT/keyboard 60 
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R-byte settings 
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tape data management interface 
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write 54 
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